gitx.do 0.0.1

package/dist/ops/commit-traversal.d.ts

@@ -0,0 +1,209 @@
+/**
+ * Commit Graph Traversal
+ *
+ * Provides functionality for walking commit graphs, finding ancestors,
+ * topological sorting, and revision range parsing.
+ */
+import { CommitObject } from '../types/objects';
+import type { CommitProvider } from '../types/storage';
+export type { CommitProvider };
+/**
+ * Sorting strategy for commit traversal
+ */
+export type SortStrategy = 'topological' | 'date' | 'author-date' | 'none';
+/**
+ * Options for commit traversal
+ */
+export interface TraversalOptions {
+    /** Maximum number of commits to return */
+    maxCount?: number;
+    /** Skip the first N commits */
+    skip?: number;
+    /** Only include commits that modify these paths */
+    paths?: string[];
+    /** Sorting strategy */
+    sort?: SortStrategy;
+    /** Whether to reverse the output order */
+    reverse?: boolean;
+    /** Starting commit SHA(s) */
+    start?: string | string[];
+    /** Commits to exclude (and their ancestors) */
+    exclude?: string[];
+    /** Include merge commits */
+    includeMerges?: boolean;
+    /** Only include first parent (follow mainline) */
+    firstParentOnly?: boolean;
+    /** Filter by author */
+    author?: string;
+    /** Filter by committer */
+    committer?: string;
+    /** Filter by date range (after) */
+    after?: Date;
+    /** Filter by date range (before) */
+    before?: Date;
+    /** Grep commit message */
+    grep?: string | RegExp;
+}
+/**
+ * Result of parsing a revision range
+ */
+export interface RevisionRange {
+    /** Type of range: '..' for A..B, '...' for A...B, 'single' for single ref */
+    type: 'two-dot' | 'three-dot' | 'single';
+    /** Left side of range (or single commit) */
+    left: string;
+    /** Right side of range (undefined for single) */
+    right?: string;
+}
+/**
+ * Commit with additional traversal metadata
+ */
+export interface TraversalCommit {
+    /** The commit object */
+    commit: CommitObject;
+    /** SHA of this commit */
+    sha: string;
+    /** Depth from starting commit(s) */
+    depth: number;
+    /** Whether this is a merge commit */
+    isMerge: boolean;
+}
+/**
+ * Walker for traversing commit graphs
+ *
+ * Supports various traversal strategies including topological sorting,
+ * date-based sorting, path filtering, and revision ranges.
+ */
+export declare class CommitWalker {
+    private provider;
+    private options;
+    private visited;
+    private hidden;
+    private queue;
+    private hiddenExpanded;
+    constructor(provider: CommitProvider, options?: TraversalOptions);
+    /**
+     * Reset the walker state
+     */
+    reset(): void;
+    /**
+     * Add a starting commit to the walker
+     */
+    push(sha: string): void;
+    /**
+     * Hide a commit and its ancestors from the walk
+     */
+    hide(sha: string): void;
+    /**
+     * Expand hidden commits to include all ancestors
+     */
+    private expandHidden;
+    /**
+     * Get the next commit in the walk
+     */
+    next(): Promise<TraversalCommit | null>;
+    /**
+     * Check if there are more commits to walk
+     */
+    hasNext(): boolean;
+    /**
+     * Iterate over all commits matching the options
+     */
+    [Symbol.asyncIterator](): AsyncIterableIterator<TraversalCommit>;
+}
+/**
+ * Walk commits starting from the given SHA(s)
+ *
+ * @param provider - The commit provider for fetching commits
+ * @param start - Starting commit SHA or array of SHAs
+ * @param options - Traversal options
+ * @yields TraversalCommit objects in the requested order
+ */
+export declare function walkCommits(provider: CommitProvider, start: string | string[], options?: TraversalOptions): AsyncGenerator<TraversalCommit, void, unknown>;
+/**
+ * Check if commit A is an ancestor of commit B
+ *
+ * @param provider - The commit provider for fetching commits
+ * @param ancestor - Potential ancestor commit SHA
+ * @param descendant - Potential descendant commit SHA
+ * @returns true if ancestor is reachable from descendant
+ */
+export declare function isAncestor(provider: CommitProvider, ancestor: string, descendant: string): Promise<boolean>;
+/**
+ * Find the common ancestor(s) of two commits
+ *
+ * @param provider - The commit provider for fetching commits
+ * @param commit1 - First commit SHA
+ * @param commit2 - Second commit SHA
+ * @param all - If true, return all common ancestors; if false, return only the best one
+ * @returns The common ancestor SHA(s), or null if none found
+ */
+export declare function findCommonAncestor(provider: CommitProvider, commit1: string, commit2: string, all?: boolean): Promise<string | string[] | null>;
+/**
+ * Find the merge base(s) of multiple commits
+ *
+ * @param provider - The commit provider for fetching commits
+ * @param commits - Array of commit SHAs
+ * @returns The merge base SHA(s)
+ */
+export declare function findMergeBase(provider: CommitProvider, commits: string[]): Promise<string[]>;
+/**
+ * Parse a revision range specification
+ *
+ * Supports:
+ * - Single commit: "abc123"
+ * - Two-dot range: "A..B" (commits reachable from B but not from A)
+ * - Three-dot range: "A...B" (symmetric difference)
+ * - Caret exclusion: "^A B" (B excluding A)
+ *
+ * @param spec - The revision specification string
+ * @returns Parsed revision range
+ */
+export declare function parseRevisionRange(spec: string): RevisionRange;
+/**
+ * Expand a revision range into include/exclude commit sets
+ *
+ * @param provider - The commit provider for fetching commits
+ * @param range - The parsed revision range
+ * @returns Object with include and exclude commit arrays
+ */
+export declare function expandRevisionRange(provider: CommitProvider, range: RevisionRange): Promise<{
+    include: string[];
+    exclude: string[];
+}>;
+/**
+ * Sort commits topologically (children before parents)
+ *
+ * @param provider - The commit provider for fetching commits
+ * @param commits - Array of commit SHAs to sort
+ * @returns Sorted array of commit SHAs
+ */
+export declare function topologicalSort(provider: CommitProvider, commits: string[]): Promise<string[]>;
+/**
+ * Sort commits by date
+ *
+ * @param provider - The commit provider for fetching commits
+ * @param commits - Array of commit SHAs to sort
+ * @param useAuthorDate - If true, use author date; otherwise use committer date
+ * @returns Sorted array of commit SHAs (newest first)
+ */
+export declare function sortByDate(provider: CommitProvider, commits: string[], useAuthorDate?: boolean): Promise<string[]>;
+/**
+ * Get all commits between two commits (exclusive of start, inclusive of end)
+ *
+ * @param provider - The commit provider for fetching commits
+ * @param start - Starting commit SHA (exclusive)
+ * @param end - Ending commit SHA (inclusive)
+ * @returns Array of commit SHAs
+ */
+export declare function getCommitsBetween(provider: CommitProvider, start: string, end: string): Promise<string[]>;
+/**
+ * Count the number of commits reachable from a commit
+ *
+ * @param provider - The commit provider for fetching commits
+ * @param sha - Starting commit SHA
+ * @param maxDepth - Maximum depth to count
+ * @returns Number of reachable commits
+ */
+export declare function countCommits(provider: CommitProvider, sha: string, maxDepth?: number): Promise<number>;
+//# sourceMappingURL=commit-traversal.d.ts.map

package/dist/ops/commit-traversal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"commit-traversal.d.ts","sourceRoot":"","sources":["../../src/ops/commit-traversal.ts"],"names":[],"mappings":"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"}