feat: implement Repository.getFileCreatedDate method with async support (#100)

* Initial plan

* Initial analysis of simple-git repository for implementing getFileCreatedDate

Co-authored-by: Brooooooklyn <3468483+Brooooooklyn@users.noreply.github.com>

* Implement getFileCreatedDate and getFileCreatedDateAsync methods with comprehensive tests

Co-authored-by: Brooooooklyn <3468483+Brooooooklyn@users.noreply.github.com>

* Fix cargo fmt and cargo clippy warnings

Co-authored-by: Brooooooklyn <3468483+Brooooooklyn@users.noreply.github.com>

---------

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: Brooooooklyn <3468483+Brooooooklyn@users.noreply.github.com>

Author: Copilot

__test__/repo.spec.mjs

@@ -33,6 +33,58 @@ test("Date should be equal with cli", (t) => {
   }
 });
 
+test("Created date should be equal with cli", (t) => {
+  const { repo } = t.context;
+  if (process.env.CI) {
+    t.notThrows(() => repo.getFileCreatedDate(join("src", "lib.rs")));
+  } else {
+    t.deepEqual(
+      new Date(
+        execSync("git log --reverse --format=%cd --date=iso src/lib.rs", {
+          cwd: workDir,
+        })
+          .toString("utf8")
+          .split('\n')[0]
+          .trim(),
+      ).valueOf(),
+      repo.getFileCreatedDate(join("src", "lib.rs")),
+    );
+  }
+});
+
+test("Created date async should work", async (t) => {
+  const { repo } = t.context;
+  if (process.env.CI) {
+    await t.notThrowsAsync(() => repo.getFileCreatedDateAsync(join("src", "lib.rs")));
+  } else {
+    const expectedDate = new Date(
+      execSync("git log --reverse --format=%cd --date=iso src/lib.rs", {
+        cwd: workDir,
+      })
+        .toString("utf8")
+        .split('\n')[0]
+        .trim(),
+    ).valueOf();
+    
+    const actualDate = await repo.getFileCreatedDateAsync(join("src", "lib.rs"));
+    t.deepEqual(expectedDate, actualDate);
+  }
+});
+
+test("Created date should throw for non-existent file", (t) => {
+  const { repo } = t.context;
+  t.throws(() => repo.getFileCreatedDate("non-existent-file.txt"), {
+    message: /Failed to get created date for/
+  });
+});
+
+test("Created date async should throw for non-existent file", async (t) => {
+  const { repo } = t.context;
+  await t.throwsAsync(() => repo.getFileCreatedDateAsync("non-existent-file.txt"), {
+    message: /Failed to get created date for/
+  });
+});
+
 test("Should be able to resolve head", (t) => {
   const { repo } = t.context;
   t.is(

index.d.ts

@@ -23,7 +23,6 @@ export declare class Commit {
   /** Get the tree pointed to by this commit. */
   tree(): Tree
   /**
-   *
    * The returned message will be slightly prettified by removing any
    * potential leading newlines.
    *
@@ -182,9 +181,18 @@ export declare class Cred {
   credtype(): CredentialType
 }
 
-/** An iterator over the diffs in a delta */
-export declare class Deltas {
-  [Symbol.iterator](): Iterator<DiffDelta, void, void>
+/**
+ * An iterator over the diffs in a delta
+ *
+ * This type extends JavaScript's `Iterator`, and so has the iterator helper
+ * methods. It may extend the upcoming TypeScript `Iterator` class in the future.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Iterator#iterator_helper_methods
+ * @see https://www.typescriptlang.org/docs/handbook/release-notes/typescript-5-6.html#iterator-helper-methods
+ */
+export declare class Deltas extends Iterator<DiffDelta, void, void> {
+
+  next(value?: void): IteratorResult<DiffDelta, void>
 }
 
 export declare class Diff {
@@ -276,7 +284,6 @@ export declare class FetchOptions {
   /**
    * Set fetch depth, a value less or equal to 0 is interpreted as pull
    * everything (effectively the same as not declaring a limit depth).
-   *
    */
   depth(depth: number): this
   /**
@@ -474,7 +481,6 @@ export declare class Remote {
    *
    * Convenience function to connect to a remote, download the data,
    * disconnect and update the remote-tracking branches.
-   *
    */
   fetch(refspecs: Array<string>, fetchOptions?: FetchOptions | undefined | null): void
   /** Update the tips to the new state */
@@ -838,10 +844,18 @@ export declare class Repository {
   revWalk(): RevWalk
   getFileLatestModifiedDate(filepath: string): number
   getFileLatestModifiedDateAsync(filepath: string, signal?: AbortSignal | undefined | null): Promise<number>
+  getFileCreatedDate(filepath: string): number
+  getFileCreatedDateAsync(filepath: string, signal?: AbortSignal | undefined | null): Promise<number>
 }
 
-export declare class RevWalk {
-  [Symbol.iterator](): Iterator<string, void, void>
+/**
+ * This type extends JavaScript's `Iterator`, and so has the iterator helper
+ * methods. It may extend the upcoming TypeScript `Iterator` class in the future.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Iterator#iterator_helper_methods
+ * @see https://www.typescriptlang.org/docs/handbook/release-notes/typescript-5-6.html#iterator-helper-methods
+ */
+export declare class RevWalk extends Iterator<string, void, void> {
   /**
    * Reset a revwalk to allow re-configuring it.
    *
@@ -927,6 +941,7 @@ export declare class RevWalk {
    * The reference must point to a commitish.
    */
   hideRef(reference: string): this
+  next(value?: void): IteratorResult<string, void>
 }
 
 /**
@@ -1035,8 +1050,16 @@ export declare class TreeEntry {
   toObject(repo: Repository): GitObject
 }
 
-export declare class TreeIter {
-  [Symbol.iterator](): Iterator<TreeEntry, void, void>
+/**
+ * This type extends JavaScript's `Iterator`, and so has the iterator helper
+ * methods. It may extend the upcoming TypeScript `Iterator` class in the future.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Iterator#iterator_helper_methods
+ * @see https://www.typescriptlang.org/docs/handbook/release-notes/typescript-5-6.html#iterator-helper-methods
+ */
+export declare class TreeIter extends Iterator<TreeEntry, void, void> {
+
+  next(value?: void): IteratorResult<TreeEntry, void>
 }
 
 /** Automatic tag following options. */

src/repo.rs

@@ -108,6 +108,13 @@ pub struct GitDateTask {
 
 unsafe impl Send for GitDateTask {}
 
+pub struct GitCreatedDateTask {
+  repo: RwLock<napi::bindgen_prelude::Reference<Repository>>,
+  filepath: String,
+}
+
+unsafe impl Send for GitCreatedDateTask {}
+
 #[napi]
 impl Task for GitDateTask {
   type Output = i64;
@@ -133,6 +140,34 @@ impl Task for GitDateTask {
   }
 }
 
+#[napi]
+impl Task for GitCreatedDateTask {
+  type Output = i64;
+  type JsValue = i64;
+
+  fn compute(&mut self) -> napi::Result<Self::Output> {
+    get_file_created_date(
+      &self
+        .repo
+        .read()
+        .map_err(|err| napi::Error::new(Status::GenericFailure, format!("{err}")))?
+        .inner,
+      &self.filepath,
+    )
+    .convert_without_message()
+    .and_then(|value| {
+      value.expect_not_null(format!(
+        "Failed to get created date for [{}]",
+        &self.filepath
+      ))
+    })
+  }
+
+  fn resolve(&mut self, _env: napi::Env, output: Self::Output) -> napi::Result<Self::JsValue> {
+    Ok(output)
+  }
+}
+
 #[napi]
 pub struct Repository {
   pub(crate) inner: git2::Repository,
@@ -876,6 +911,31 @@ impl Repository {
       signal,
     ))
   }
+
+  #[napi]
+  pub fn get_file_created_date(&self, filepath: String) -> Result<i64> {
+    get_file_created_date(&self.inner, &filepath)
+      .convert_without_message()
+      .and_then(|value| {
+        value.expect_not_null(format!("Failed to get created date for [{filepath}]"))
+      })
+  }
+
+  #[napi]
+  pub fn get_file_created_date_async(
+    &self,
+    self_ref: Reference<Repository>,
+    filepath: String,
+    signal: Option<AbortSignal>,
+  ) -> Result<AsyncTask<GitCreatedDateTask>> {
+    Ok(AsyncTask::with_optional_signal(
+      GitCreatedDateTask {
+        repo: RwLock::new(self_ref),
+        filepath,
+      },
+      signal,
+    ))
+  }
 }
 
 fn get_file_modified_date(
@@ -923,3 +983,30 @@ fn get_file_modified_date(
       }),
   )
 }
+
+fn get_file_created_date(
+  repo: &git2::Repository,
+  filepath: &str,
+) -> std::result::Result<Option<i64>, git2::Error> {
+  // TODO: Add rename detection support using git2::DiffFindOptions for full `git log --follow` semantics
+  let mut rev_walk = repo.revwalk()?;
+  rev_walk.push_head()?;
+  rev_walk.set_sorting(git2::Sort::TIME & git2::Sort::TOPOLOGICAL)?;
+  let path = PathBuf::from(filepath);
+
+  let mut earliest_commit_time: Option<i64> = None;
+
+  // Traverse all commits to find the earliest one that contains the file
+  for oid in rev_walk.by_ref().filter_map(|oid| oid.ok()) {
+    if let Ok(commit) = repo.find_commit(oid)
+      && let Ok(tree) = commit.tree()
+    {
+      // Check if the file exists in this commit's tree
+      if tree.get_path(&path).is_ok() {
+        earliest_commit_time = Some(commit.time().seconds() * 1000);
+      }
+    }
+  }
+
+  Ok(earliest_commit_time)
+}