feat: implements blame features (#107)

Author: other-yuka

index.d.ts

@@ -3,6 +3,72 @@
 
 /* auto-generated by NAPI-RS */
 
+/**
+ * Represents a hunk of a blame operation, which is a range of lines
+ * and information about who last modified them.
+ */
+export interface BlameHunk {
+  /** The oid of the commit where this line was last changed. */
+  finalCommitId: string
+  /** The 1-based line number in the final file where this hunk starts. */
+  finalStartLineNumber: number
+  /** The number of lines in this hunk. */
+  linesInHunk: number
+  /** The signature of the commit where this line was last changed. */
+  finalSignature?: Signature
+  /** The path to the file where this line was originally written. */
+  path?: string
+  /** The 1-based line number in the original file where this hunk starts. */
+  origStartLineNumber: number
+  /** The oid of the commit where this line was originally written. */
+  origCommitId: string
+  /** The signature of the commit where this line was originally written. */
+  origSignature?: Signature
+  /**
+   * True if the hunk has been determined to be a boundary commit (the commit
+   * when the file was first introduced to the repository).
+   */
+  isBoundary: boolean
+}
+/** Options for controlling blame behavior */
+export interface BlameOptions {
+  /** The minimum line number to blame (1-based index) */
+  minLine?: number
+  /** The maximum line number to blame (1-based index) */
+  maxLine?: number
+  /**
+   * The oid of the newest commit to consider. The blame algorithm will stop
+   * when this commit is reached.
+   */
+  newestCommit?: string
+  /**
+   * The oid of the oldest commit to consider. The blame algorithm will
+   * stop when this commit is reached.
+   */
+  oldestCommit?: string
+  /**
+   * The path to the file being worked on. Path has to be relative to the
+   * repo root.
+   */
+  path?: string
+  /**
+   * Track lines that have moved within a file. This is the git-blame -M
+   * option.
+   */
+  trackLinesMovement?: boolean
+  /** Restrict search to commits reachable following only first parents. */
+  firstParent?: boolean
+  /** Ignore whitespace differences. */
+  ignoreWhitespace?: boolean
+  /** Track lines that have been copied from another file that exists in any commit. */
+  trackCopiesAnyCommitCopies?: boolean
+  /** Track lines that have been copied from another file that exists in the same commit. */
+  trackCopiesSameCommitCopies?: boolean
+  /** Track lines that have moved across files in the same commit. */
+  trackCopiesSameCommitMoves?: boolean
+  /** Use mailmap file to map author and committer names and email addresses to canonical real names and email addresses. */
+  useMailmap?: boolean
+}
 /**
  * Ensure the branch name is well-formed.
  *
@@ -1420,6 +1486,146 @@ export interface CreateLightweightTagOptions {
  * - `PostOrder` : Runs the traversal in post-order.
  */
 export type TreeWalkMode = 'PreOrder' | 'PostOrder';
+/** A wrapper around git2::Blame providing Node.js bindings */
+export declare class Blame {
+  /**
+   * Gets the number of hunks in the blame result
+   *
+   * @category Blame/Methods
+   * @signature
+   * ```ts
+   * class Blame {
+   *   getHunkCount(): number;
+   * }
+   * ```
+   *
+   * @returns The number of hunks in the blame result
+   */
+  getHunkCount(): number
+  /**
+   * Checks if the blame result is empty
+   *
+   * @category Blame/Methods
+   * @signature
+   * ```ts
+   * class Blame {
+   *   isEmpty(): boolean;
+   * }
+   * ```
+   *
+   * @returns True if the blame result contains no hunks
+   */
+  isEmpty(): boolean
+  /**
+   * Gets blame information for the specified index
+   *
+   * @category Blame/Methods
+   * @signature
+   * ```ts
+   * class Blame {
+   *   getHunkByIndex(index: number): BlameHunk;
+   * }
+   * ```
+   *
+   * @param {number} index - Index of the hunk to get (0-based)
+   * @returns Blame information for the specified index
+   * @throws If no hunk is found at the index
+   */
+  getHunkByIndex(index: number): BlameHunk
+  /**
+   * Gets blame information for the specified line
+   *
+   * @category Blame/Methods
+   * @signature
+   * ```ts
+   * class Blame {
+   *   getHunkByLine(line: number): BlameHunk;
+   * }
+   * ```
+   *
+   * @param {number} line - Line number to get blame information for (1-based)
+   * @returns Blame information for the specified line
+   * @throws If no hunk is found for the line
+   */
+  getHunkByLine(line: number): BlameHunk
+  /**
+   * Gets all blame hunks as an iterator
+   *
+   * @category Blame/Methods
+   * @signature
+   * ```ts
+   * class Blame {
+   *   iter(): Generator<BlameHunk>;
+   * }
+   * ```
+   *
+   * @returns Iterator of all blame hunks
+   * @example
+   * ```ts
+   * // Using for...of loop
+   * for (const hunk of blame.iter()) {
+   *   console.log(hunk.finalCommitId);
+   * }
+   *
+   * // Using spread operator to collect all hunks
+   * const hunks = [...blame.iter()];
+   * ```
+   */
+  iter(): BlameHunks
+  /**
+   * Collects blame hunks by scanning file lines as an iterator
+   *
+   * @category Blame/Methods
+   * @signature
+   * ```ts
+   * class Blame {
+   *   iterByLine(): Generator<BlameHunk>;
+   * }
+   * ```
+   *
+   * @returns Iterator of blame hunks collected by line scanning
+   * @example
+   * ```ts
+   * // Using for...of loop
+   * for (const hunk of blame.iterByLine()) {
+   *   console.log(hunk.finalCommitId);
+   * }
+   *
+   * // Using spread operator to collect all hunks
+   * const hunks = [...blame.iterByLine()];
+   * ```
+   */
+  iterByLine(): BlameHunksByLine
+  /**
+   * Generates blame information from an in-memory buffer
+   *
+   * @category Blame/Methods
+   * @signature
+   * ```ts
+   * class Blame {
+   *   buffer(buffer: Buffer): Blame;
+   * }
+   * ```
+   *
+   * @example
+   * ```ts
+   * const buffer = Buffer.from('modified content');
+   * const bufferBlame = blame.buffer(buffer);
+   * ```
+   *
+   * @param {Buffer} buffer - Buffer containing file content to blame
+   * @returns A new Blame object for the buffer content
+   */
+  buffer(buffer: Buffer): Blame
+}
+/** An iterator over blame hunks. */
+export declare class BlameHunks {
+  [Symbol.iterator](): Iterator<BlameHunk, void, void>
+}
+/** Iterator over blame hunks collected line by line. */
+export declare class BlameHunksByLine {
+  [Symbol.iterator](): Iterator<BlameHunk, void, void>
+}
 /**
  * A class to represent a git [blob][1].
  * [1]: https://git-scm.com/book/en/Git-Internals-Git-Objects
@@ -3413,6 +3619,35 @@ export declare class Remote {
  * This class corresponds to a git repository in libgit2.
  */
 export declare class Repository {
+  /**
+   * Creates a blame object for the file at the given path
+   *
+   * @category Repository/Methods
+   * @signature
+   * ```ts
+   * class Repository {
+   *   blameFile(path: string, options?: BlameOptions): Blame;
+   * }
+   * ```
+   *
+   * @example
+   * ```ts
+   * // Blame the entire file
+   * const blame = repo.blameFile('path/to/file.js');
+   *
+   * // Blame a single line
+   * const lineBlame = repo.blameFile('path/to/file.js', { minLine: 10, maxLine: 10 });
+   *
+   * // Blame a range of lines
+   * const rangeBlame = repo.blameFile('path/to/file.js', { minLine: 5, maxLine: 15 });
+   * ```
+   *
+   * @param {string} path - Path to the file to blame
+   * @param {BlameOptions} [options] - Options to control blame behavior
+   * @returns Blame object for the specified file
+   * @throws If the file doesn't exist or can't be opened
+   */
+  blameFile(path: string, options?: BlameOptions | undefined | null): Blame
   /**
    * Create a new branch pointing at a target commit
    *