feat(note): add bindings and api

lib/src/bindings/note.dart

@@ -0,0 +1,146 @@
+import 'dart:ffi';
+import 'package:ffi/ffi.dart';
+import '../error.dart';
+import '../util.dart';
+import 'libgit2_bindings.dart';
+
+/// Returns list of notes for repository.
+///
+/// Notes must be freed manually by the user.
+///
+/// Throws a [LibGit2Error] if error occured.
+List<Map<String, Pointer>> list(Pointer<git_repository> repo) {
+  final notesRef = 'refs/notes/commits'.toNativeUtf8().cast<Int8>();
+  final iterator = calloc<Pointer<git_iterator>>();
+  final iteratorError = libgit2.git_note_iterator_new(iterator, repo, notesRef);
+
+  if (iteratorError < 0) {
+    throw LibGit2Error(libgit2.git_error_last());
+  }
+
+  var result = <Map<String, Pointer>>[];
+  var nextError = 0;
+
+  while (nextError >= 0) {
+    final noteId = calloc<git_oid>();
+    var annotatedId = calloc<git_oid>();
+    nextError = libgit2.git_note_next(noteId, annotatedId, iterator.value);
+    if (nextError >= 0) {
+      final out = calloc<Pointer<git_note>>();
+      final error = libgit2.git_note_read(out, repo, notesRef, annotatedId);
+
+      calloc.free(noteId);
+
+      if (error < 0) {
+        throw LibGit2Error(libgit2.git_error_last());
+      } else {
+        result.add({'note': out.value, 'annotatedId': annotatedId});
+      }
+    } else {
+      break;
+    }
+  }
+
+  calloc.free(notesRef);
+  libgit2.git_note_iterator_free(iterator.value);
+
+  return result;
+}
+
+/// Read the note for an object.
+///
+/// The note must be freed manually by the user.
+///
+/// Throws a [LibGit2Error] if error occured.
+Pointer<git_note> lookup({
+  required Pointer<git_repository> repoPointer,
+  required Pointer<git_oid> oidPointer,
+  String notesRef = 'refs/notes/commits',
+}) {
+  final out = calloc<Pointer<git_note>>();
+  final notesRefC = notesRef.toNativeUtf8().cast<Int8>();
+  final error = libgit2.git_note_read(out, repoPointer, notesRefC, oidPointer);
+
+  calloc.free(notesRefC);
+
+  if (error < 0) {
+    throw LibGit2Error(libgit2.git_error_last());
+  } else {
+    return out.value;
+  }
+}
+
+/// Add a note for an object.
+///
+/// Throws a [LibGit2Error] if error occured.
+Pointer<git_oid> create({
+  required Pointer<git_repository> repoPointer,
+  String notesRef = 'refs/notes/commits',
+  required Pointer<git_signature> authorPointer,
+  required Pointer<git_signature> committerPointer,
+  required Pointer<git_oid> oidPointer,
+  required String note,
+  bool force = false,
+}) {
+  final out = calloc<git_oid>();
+  final notesRefC = notesRef.toNativeUtf8().cast<Int8>();
+  final noteC = note.toNativeUtf8().cast<Int8>();
+  final forceC = force ? 1 : 0;
+  final error = libgit2.git_note_create(
+    out,
+    repoPointer,
+    notesRefC,
+    authorPointer,
+    committerPointer,
+    oidPointer,
+    noteC,
+    forceC,
+  );
+
+  calloc.free(notesRefC);
+  calloc.free(noteC);
+
+  if (error < 0) {
+    throw LibGit2Error(libgit2.git_error_last());
+  } else {
+    return out;
+  }
+}
+
+/// Remove the note for an object.
+///
+/// Throws a [LibGit2Error] if error occured.
+void remove({
+  required Pointer<git_repository> repoPointer,
+  String notesRef = 'refs/notes/commits',
+  required Pointer<git_signature> authorPointer,
+  required Pointer<git_signature> committerPointer,
+  required Pointer<git_oid> oidPointer,
+}) {
+  final notesRefC = notesRef.toNativeUtf8().cast<Int8>();
+
+  final error = libgit2.git_note_remove(
+    repoPointer,
+    notesRefC,
+    authorPointer,
+    committerPointer,
+    oidPointer,
+  );
+
+  calloc.free(notesRefC);
+
+  if (error < 0) {
+    throw LibGit2Error(libgit2.git_error_last());
+  }
+}
+
+/// Get the note object's id.
+Pointer<git_oid> id(Pointer<git_note> note) => libgit2.git_note_id(note);
+
+/// Get the note message.
+String message(Pointer<git_note> note) {
+  return libgit2.git_note_message(note).cast<Utf8>().toDartString();
+}
+
+/// Free memory allocated for note object.
+void free(Pointer<git_note> note) => libgit2.git_note_free(note);

lib/src/note.dart

@@ -0,0 +1,121 @@
+import 'dart:ffi';
+import 'bindings/libgit2_bindings.dart';
+import 'bindings/note.dart' as bindings;
+import 'oid.dart';
+import 'repository.dart';
+import 'signature.dart';
+
+class Notes {
+  /// Initializes a new instance of the [Notes] class from
+  /// provided [Repository] object.
+  Notes(Repository repo) {
+    _repoPointer = repo.pointer;
+  }
+
+  /// Pointer to memory address for allocated repository object.
+  late final Pointer<git_repository> _repoPointer;
+
+  /// Reads the note for an object.
+  ///
+  /// The note must be freed manually by the user.
+  ///
+  /// Throws a [LibGit2Error] if error occured.
+  static Note lookup({
+    required Repository repo,
+    required Oid annotatedId,
+    String notesRef = 'refs/notes/commits',
+  }) {
+    final note = bindings.lookup(
+      repoPointer: repo.pointer,
+      oidPointer: annotatedId.pointer,
+      notesRef: notesRef,
+    );
+
+    return Note(note, annotatedId.pointer, repo.pointer);
+  }
+
+  /// Adds a note for an [object].
+  ///
+  /// Throws a [LibGit2Error] if error occured.
+  static Oid create({
+    required Repository repo,
+    required Signature author,
+    required Signature committer,
+    required Oid object,
+    required String note,
+    String notesRef = 'refs/notes/commits',
+    bool force = false,
+  }) {
+    return Oid(bindings.create(
+      repoPointer: repo.pointer,
+      authorPointer: author.pointer,
+      committerPointer: committer.pointer,
+      oidPointer: object.pointer,
+      note: note,
+      notesRef: notesRef,
+      force: force,
+    ));
+  }
+
+  /// Returns list of notes for repository.
+  ///
+  /// Notes must be freed manually by the user.
+  ///
+  /// Throws a [LibGit2Error] if error occured.
+  List<Note> get list {
+    final notesPointers = bindings.list(_repoPointer);
+    var result = <Note>[];
+    for (var note in notesPointers) {
+      result.add(Note(
+        note['note'] as Pointer<git_note>,
+        note['annotatedId'] as Pointer<git_oid>,
+        _repoPointer,
+      ));
+    }
+
+    return result;
+  }
+}
+
+class Note {
+  /// Initializes a new instance of the [Note] class from provided
+  /// pointer to note object in memory.
+  Note(this._notePointer, this._annotatedIdPointer, this._repoPointer);
+
+  /// Pointer to memory address for allocated note object.
+  final Pointer<git_note> _notePointer;
+
+  /// Pointer to memory address for allocated annotetedId object.
+  final Pointer<git_oid> _annotatedIdPointer;
+
+  /// Pointer to memory address for allocated repository object.
+  final Pointer<git_repository> _repoPointer;
+
+  /// Removes the note for an [object].
+  ///
+  /// Throws a [LibGit2Error] if error occured.
+  void remove({
+    required Signature author,
+    required Signature committer,
+    String notesRef = 'refs/notes/commits',
+  }) {
+    bindings.remove(
+      repoPointer: _repoPointer,
+      authorPointer: author.pointer,
+      committerPointer: committer.pointer,
+      oidPointer: annotatedId.pointer,
+    );
+  }
+
+  /// Returns the note object's [Oid].
+  Oid get id => Oid(bindings.id(_notePointer));
+
+  /// Returns the note message.
+  String get message => bindings.message(_notePointer);
+
+  /// Returns the [Oid] of the git object being annotated.
+  Oid get annotatedId => Oid(_annotatedIdPointer);
+
+  /// Releases memory allocated for note object.
+  void free() => bindings.free(_notePointer);
+}

lib/src/repository.dart

@@ -1118,4 +1118,49 @@ class Repository {
       maxLine: maxLine,
     );
   }
+
+  /// Returns list of notes for repository.
+  ///
+  /// Notes must be freed manually.
+  ///
+  /// Throws a [LibGit2Error] if error occured.
+  List<Note> get notes => Notes(this).list;
+
+  /// Reads the note for an object.
+  ///
+  /// The note must be freed manually.
+  ///
+  /// Throws a [LibGit2Error] if error occured.
+  Note lookupNote({
+    required Oid annotatedId,
+    String notesRef = 'refs/notes/commits',
+  }) {
+    return Notes.lookup(
+      repo: this,
+      annotatedId: annotatedId,
+      notesRef: notesRef,
+    );
+  }
+
+  /// Adds a note for an [object].
+  ///
+  /// Throws a [LibGit2Error] if error occured.
+  Oid createNote({
+    required Signature author,
+    required Signature committer,
+    required Oid object,
+    required String note,
+    String notesRef = 'refs/notes/commits',
+    bool force = false,
+  }) {
+    return Notes.create(
+      repo: this,
+      author: author,
+      committer: committer,
+      object: object,
+      note: note,
+      notesRef: notesRef,
+      force: force,
+    );
+  }
 }