feat: impl revparse, commit, signature, object (#17)

* add revparse test fixture

* impl revparse

* revparse mode to bitflag

* remove unused fixtures

* docs, object

Author: seokju-na

Cargo.toml

@@ -7,9 +7,10 @@ version = "0.0.0"
 crate-type = ["cdylib"]
 
 [dependencies]
-git2 = { version = "0.19.0", features = ["vendored-libgit2", "vendored-openssl"] }
-# Default enable napi4 feature, see https://nodejs.org/api/n-api.html#node-api-version-matrix
-napi        = { version = "2.16.13", default-features = false, features = ["napi4"] }
+bitflags    = "2.1.0"
+chrono      = "0.4"
+git2        = { version = "0.19.0", features = ["vendored-libgit2", "vendored-openssl"] }
+napi        = { version = "2.16.13", default-features = false, features = ["napi4", "chrono_date"] }
 napi-derive = "2.16.12"
 serde       = { version = "1", features = ["derive"] }
 thiserror   = "2.0.3"

index.d.ts

@@ -184,10 +184,129 @@ export interface RepositoryCloneOptions {
   recursive?: boolean;
   fetch?: FetchOptions;
 }
+/** Creates a new repository in the specified folder. */
 export declare function initRepository(path: string, options?: RepositoryInitOptions | undefined | null, signal?: AbortSignal | undefined | null): Promise<Repository>
+/** Attempt to open an already-existing repository at `path`. */
 export declare function openRepository(path: string, options?: RepositoryOpenOptions | undefined | null, signal?: AbortSignal | undefined | null): Promise<Repository>
+/**
+ * Attempt to open an already-existing repository at or above `path`
+ *
+ * This starts at `path` and looks up the filesystem hierarchy
+ * until it finds a repository.
+ */
 export declare function discoverRepository(path: string, signal?: AbortSignal | undefined | null): Promise<Repository>
+/**
+ * Clone a remote repository.
+ *
+ * This will use the options configured so far to clone the specified URL
+ * into the specified local path.
+ */
 export declare function cloneRepository(url: string, path: string, options?: RepositoryCloneOptions | undefined | null, signal?: AbortSignal | undefined | null): Promise<Repository>
+/** Flags for the Revspec. */
+export const enum RevparseMode {
+  /** The spec targeted a single object (1 << 0) */
+  Single = 1,
+  /** The spec targeted a range of commits (1 << 1) */
+  Range = 2,
+  /** The spec used the `...` operator, which invokes special semantics. (1 << 2) */
+  MergeBase = 4
+}
+/** Check revparse mode contains specific flags. */
+export declare function revparseModeContains(source: number, target: number): boolean
+/** A revspec represents a range of revisions within a repository. */
+export interface Revspec {
+  /** Access the `from` range of this revspec. */
+  from?: string
+  /** Access the `to` range of this revspec. */
+  to?: string
+  /** Returns the intent of the revspec. */
+  mode: number
+}
+/**
+ * A Signature is used to indicate authorship of various actions throughout the
+ * library.
+ *
+ * Signatures contain a name, email, and timestamp.
+ */
+export interface Signature {
+  /** Name on the signature. */
+  name: string
+  /** Email on the signature. */
+  email: string
+  /** Time in seconds, from epoch */
+  timestamp: number
+}
+export interface CreateSignatureOptions {
+  /** Time in seconds, from epoch */
+  timestamp: number
+  /** Timezone offset, in minutes */
+  offset?: number
+}
+/** Create a new action signature. */
+export declare function createSignature(name: string, email: string, options?: CreateSignatureOptions | undefined | null): Signature
+/** An enumeration all possible kinds objects may have. */
+export const enum ObjectType {
+  /** Any kind of git object */
+  Any = 0,
+  /** An object which corresponds to a git commit */
+  Commit = 1,
+  /** An object which corresponds to a git tree */
+  Tree = 2,
+  /** An object which corresponds to a git blob */
+  Blob = 3,
+  /** An object which corresponds to a git tag */
+  Tag = 4
+}
+/** A structure to represent a git commit */
+export declare class Commit {
+  /** Get the id (SHA1) of a repository commit */
+  id(): string
+  /** Get the author of this commit. */
+  author(): Signature
+  /** Get the committer of this commit. */
+  committer(): Signature
+  /**
+   * Get the full message of a commit.
+   *
+   * The returned message will be slightly prettified by removing any
+   * potential leading newlines.
+   *
+   * Throws error if the message is not valid utf-8
+   */
+  message(): string
+  /**
+   * Get the short "summary" of the git commit message.
+   *
+   * The returned message is the summary of the commit, comprising the first
+   * paragraph of the message with whitespace trimmed and squashed.
+   *
+   * Throws error if the summary is not valid utf-8.
+   */
+  summary(): string | null
+  /**
+   * Get the long "body" of the git commit message.
+   *
+   * The returned message is the body of the commit, comprising everything
+   * but the first paragraph of the message. Leading and trailing whitespaces
+   * are trimmed.
+   *
+   * Throws error if the summary is not valid utf-8.
+   */
+  body(): string | null
+  /**
+   * Get the commit time (i.e. committer time) of a commit.
+   *
+   * The first element of the tuple is the time, in seconds, since the epoch.
+   * The second element is the offset, in minutes, of the time zone of the
+   * committer's preferred time zone.
+   */
+  time(): Date
+}
+/**
+ * A structure representing a [remote][1] of a git repository.
+ *
+ * [1]: http://git-scm.com/book/en/Git-Basics-Working-with-Remotes
+ */
 export declare class Remote {
   /**
    * Get the remote's name.
@@ -233,7 +352,32 @@ export declare class Remote {
   /** Get the remote’s default branch. */
   defaultBranch(signal?: AbortSignal | undefined | null): Promise<string>
 }
+/**
+ * An owned git repository, representing all state associated with the
+ * underlying filesystem.
+ *
+ * This structure corresponds to a `git_repository` in libgit2.
+ *
+ * When a repository goes out of scope, it is freed in memory but not deleted
+ * from the filesystem.
+ */
 export declare class Repository {
+  /**
+   * Lookup a reference to one of the commits in a repository.
+   *
+   * Returns `null` if the commit does not exist.
+   */
+  findCommit(oid: string): Commit | null
+  /** Lookup a reference to one of the commits in a repository. */
+  getCommit(oid: string): Commit
+  /**
+   * Lookup a reference to one of the objects in a repository.
+   *
+   * Returns `null` if the object does not exist.
+   */
+  findObject(oid: string): GitObject | null
+  /** Lookup a reference to one of the objects in a repository. */
+  getObject(oid: string): GitObject
   /** List all remotes for a given repository */
   remoteNames(): Array<string>
   /**
@@ -246,11 +390,65 @@ export declare class Repository {
   findRemote(name: string): Remote | null
   /** Add a remote with the default fetch refspec to the repository’s configuration. */
   createRemote(name: string, url: string, options?: CreateRemoteOptions | undefined | null): Remote
+  /** Tests whether this repository is a bare repository or not. */
   isBare(): boolean
+  /** Tests whether this repository is a shallow clone. */
   isShallow(): boolean
+  /** Tests whether this repository is a worktree. */
   isWorktree(): boolean
+  /** Tests whether this repository is empty. */
   isEmpty(): boolean
+  /**
+   * Returns the path to the `.git` folder for normal repositories or the
+   * repository itself for bare repositories.
+   */
   path(): string
+  /** Returns the current state of this repository */
   state(): RepositoryState
+  /**
+   * Get the path of the working directory for this repository.
+   *
+   * If this repository is bare, then `null` is returned.
+   */
   workdir(): string | null
+  /**
+   * Execute a rev-parse operation against the `spec` listed.
+   *
+   * The resulting revision specification is returned, or an error is
+   * returned if one occurs.
+   */
+  revparse(spec: string): Revspec
+  /** Find a single object, as specified by a revision string. */
+  revparseSingle(spec: string): string
+}
+/**
+ * A structure to represent a git [object][1]
+ *
+ * [1]: http://git-scm.com/book/en/Git-Internals-Git-Objects
+ */
+export declare class GitObject {
+  /** Get the id (SHA1) of a repository object */
+  id(): string
+  /**
+   * Get the object type of object.
+   *
+   * If the type is unknown, then `null` is returned.
+   */
+  type(): ObjectType | null
+  /**
+   * Recursively peel an object until an object of the specified type is met.
+   *
+   * If you pass `Any` as the target type, then the object will be
+   * peeled until the type changes (e.g. a tag will be chased until the
+   * referenced object is no longer a tag).
+   */
+  peel(objType: ObjectType): GitObject
+  /** Recursively peel an object until a commit is found */
+  peelToCommit(): Commit
+  /**
+   * Attempt to view this object as a commit.
+   *
+   * Returns `null` if the object is not actually a commit.
+   */
+  asCommit(): Commit | null
 }

index.js

@@ -0,0 +1,131 @@
+use crate::repository::Repository;
+use crate::signature::Signature;
+use chrono::{DateTime, Utc};
+use napi::bindgen_prelude::*;
+use napi_derive::napi;
+use std::ops::Deref;
+
+pub(crate) enum CommitInner {
+  Repo(SharedReference<Repository, git2::Commit<'static>>),
+  Commit(git2::Commit<'static>),
+}
+
+impl Deref for CommitInner {
+  type Target = git2::Commit<'static>;
+
+  fn deref(&self) -> &Self::Target {
+    match self {
+      Self::Repo(repo) => repo.deref(),
+      Self::Commit(commit) => commit,
+    }
+  }
+}
+
+#[napi]
+/// A structure to represent a git commit
+pub struct Commit {
+  pub(crate) inner: CommitInner,
+}
+
+#[napi]
+impl Commit {
+  #[napi]
+  /// Get the id (SHA1) of a repository commit
+  pub fn id(&self) -> String {
+    self.inner.id().to_string()
+  }
+
+  #[napi]
+  /// Get the author of this commit.
+  pub fn author(&self) -> crate::Result<Signature> {
+    let signature = Signature::try_from(self.inner.author())?;
+    Ok(signature)
+  }
+
+  #[napi]
+  /// Get the committer of this commit.
+  pub fn committer(&self) -> crate::Result<Signature> {
+    let signature = Signature::try_from(self.inner.committer())?;
+    Ok(signature)
+  }
+
+  #[napi]
+  /// Get the full message of a commit.
+  ///
+  /// The returned message will be slightly prettified by removing any
+  /// potential leading newlines.
+  ///
+  /// Throws error if the message is not valid utf-8
+  pub fn message(&self) -> crate::Result<String> {
+    let message = std::str::from_utf8(self.inner.message_raw_bytes())?.to_string();
+    Ok(message)
+  }
+
+  #[napi]
+  /// Get the short "summary" of the git commit message.
+  ///
+  /// The returned message is the summary of the commit, comprising the first
+  /// paragraph of the message with whitespace trimmed and squashed.
+  ///
+  /// Throws error if the summary is not valid utf-8.
+  pub fn summary(&self) -> crate::Result<Option<String>> {
+    let summary = match self.inner.summary_bytes() {
+      Some(bytes) => Some(std::str::from_utf8(bytes)?.to_string()),
+      None => None,
+    };
+    Ok(summary)
+  }
+
+  #[napi]
+  /// Get the long "body" of the git commit message.
+  ///
+  /// The returned message is the body of the commit, comprising everything
+  /// but the first paragraph of the message. Leading and trailing whitespaces
+  /// are trimmed.
+  ///
+  /// Throws error if the summary is not valid utf-8.
+  pub fn body(&self) -> crate::Result<Option<String>> {
+    let body = match self.inner.body_bytes() {
+      Some(bytes) => Some(std::str::from_utf8(bytes)?.to_string()),
+      None => None,
+    };
+    Ok(body)
+  }
+
+  #[napi]
+  /// Get the commit time (i.e. committer time) of a commit.
+  ///
+  /// The first element of the tuple is the time, in seconds, since the epoch.
+  /// The second element is the offset, in minutes, of the time zone of the
+  /// committer's preferred time zone.
+  pub fn time(&self) -> crate::Result<DateTime<Utc>> {
+    let time = DateTime::from_timestamp(self.inner.time().seconds(), 0).ok_or(crate::Error::InvalidTime)?;
+    Ok(time)
+  }
+}
+
+#[napi]
+impl Repository {
+  #[napi]
+  /// Lookup a reference to one of the commits in a repository.
+  ///
+  /// Returns `null` if the commit does not exist.
+  pub fn find_commit(&self, this: Reference<Repository>, env: Env, oid: String) -> Option<Commit> {
+    self.get_commit(this, env, oid).ok()
+  }
+
+  #[napi]
+  /// Lookup a reference to one of the commits in a repository.
+  pub fn get_commit(&self, this: Reference<Repository>, env: Env, oid: String) -> crate::Result<Commit> {
+    let commit = this.share_with(env, |repo| {
+      repo
+        .inner
+        .find_commit_by_prefix(&oid)
+        .map_err(crate::Error::from)
+        .map_err(|e| e.into())
+    })?;
+    Ok(Commit {
+      inner: CommitInner::Repo(commit),
+    })
+  }
+}