From 9b839ca3617b018dd970b785e650faed3fe15ca8 Mon Sep 17 00:00:00 2001 From: "coderabbitai[bot]" <136622811+coderabbitai[bot]@users.noreply.github.com> Date: Mon, 29 Sep 2025 16:05:45 +0000 Subject: [PATCH 1/2] =?UTF-8?q?=F0=9F=93=9D=20Add=20docstrings=20to=20`fea?= =?UTF-8?q?t/next-hex-task`?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Docstrings generation was requested by @flyingrobots. * https://github.com/neuroglyph/git-mind/pull/174#issuecomment-3347395660 The following files were modified: * `core/tests/unit/test_cache_strict_equality.c` * `core/tests/unit/test_journal_mixed_cbor.c` --- core/tests/unit/test_cache_strict_equality.c | 178 +++++++++++++++++++ core/tests/unit/test_journal_mixed_cbor.c | 24 +++ 2 files changed, 202 insertions(+) diff --git a/core/tests/unit/test_cache_strict_equality.c b/core/tests/unit/test_cache_strict_equality.c index f98673ae..4be865a7 100644 --- a/core/tests/unit/test_cache_strict_equality.c +++ b/core/tests/unit/test_cache_strict_equality.c @@ -25,6 +25,14 @@ typedef struct test_git_repo_port { gm_git_reference_tip_t glob_tip; } test_git_repo_port_t; +/** + * Provide the repository path for the requested kind (test stub). + * + * This stub does not implement path resolution and always returns an error + * indicating the operation is not implemented. + * + * @returns A gm_result_void_t error result containing `GM_ERR_NOT_IMPLEMENTED`. + */ static gm_result_void_t stub_repository_path(void *self, gm_git_repository_path_kind_t kind, char *out_buffer, @@ -36,6 +44,14 @@ static gm_result_void_t stub_repository_path(void *self, return gm_err_void(GM_ERROR(GM_ERR_NOT_IMPLEMENTED, "test stub")); } +/** + * Stub implementation for retrieving the current HEAD branch name used in tests. + * + * @param self Opaque pointer to the repository port instance (ignored). + * @param out_name Buffer to receive the branch name (ignored). + * @param out_name_size Size of the out_name buffer (ignored). + * @returns A gm_result_void_t representing the `GM_ERR_NOT_IMPLEMENTED` error. + */ static gm_result_void_t stub_head_branch(void *self, char *out_name, size_t out_name_size) { (void)self; @@ -44,6 +60,14 @@ static gm_result_void_t stub_head_branch(void *self, char *out_name, return gm_err_void(GM_ERROR(GM_ERR_NOT_IMPLEMENTED, "test stub")); } +/** + * Test stub for building a tree that always reports the operation as not implemented. + * + * This function does not construct or modify any tree and exists only for testing; + * it always fails with a "not implemented" error. + * + * @returns An error result with `GM_ERR_NOT_IMPLEMENTED`. + */ static gm_result_void_t stub_build_tree(void *self, const char *dir_path, gm_oid_t *out_tree_oid) { (void)self; @@ -52,6 +76,18 @@ static gm_result_void_t stub_build_tree(void *self, const char *dir_path, return gm_err_void(GM_ERROR(GM_ERR_NOT_IMPLEMENTED, "test stub")); } +/** + * Populate the output reference tip based on the provided reference name. + * + * If ref_name starts with GM_CACHE_REF_PREFIX, copies the stub's cache_tip to out_tip. + * If ref_name starts with GITMIND_EDGES_REF_PREFIX, copies the current journal tip + * (stub->journal_tips[stub->journal_tip_index]) to out_tip and advances journal_tip_index + * by one unless already at the last tip. For any other ref_name, sets out_tip to an all-zero tip. + * + * @param ref_name The reference name used to select which tip to return. + * @param out_tip Pointer to receive the selected or zeroed gm_git_reference_tip_t. + * @returns `GM_OK` on success; `GM_ERR_INVALID_ARGUMENT` if ref_name or out_tip is NULL. + */ static gm_result_void_t reference_tip(void *self, const char *ref_name, gm_git_reference_tip_t *out_tip) { test_git_repo_port_t *stub = (test_git_repo_port_t *)self; @@ -87,6 +123,17 @@ static gm_result_void_t reference_tip(void *self, const char *ref_name, return gm_ok_void(); } +/** + * Retrieve the latest reference tip matching a glob pattern from the test stub. + * + * The provided pattern is validated for non-NULL but not inspected; the function + * always returns the stub's preset glob_tip into `out_tip`. + * + * @param pattern Glob pattern to match (validated for non-NULL; otherwise ignored). + * @param out_tip Output pointer that receives the latest matching reference tip. + * @returns `gm_ok_void()` on success; `gm_err_void(GM_ERR_INVALID_ARGUMENT, ...)` + * if `pattern` or `out_tip` is NULL. + */ static gm_result_void_t reference_glob_latest(void *self, const char *pattern, gm_git_reference_tip_t *out_tip) { test_git_repo_port_t *stub = (test_git_repo_port_t *)self; @@ -99,6 +146,15 @@ static gm_result_void_t reference_glob_latest(void *self, const char *pattern, return gm_ok_void(); } +/** + * Stub implementation of reading a blob at a commit path that always fails. + * + * If provided, sets `*out_data` to NULL and `*out_size` to 0 before returning. + * + * @param out_data If non-NULL, receives NULL to indicate no data was produced. + * @param out_size If non-NULL, receives 0 to indicate zero bytes. + * @returns An error result indicating the operation is not implemented. + */ static gm_result_void_t stub_commit_read_blob(void *self, const gm_oid_t *commit_oid, const char *path, @@ -116,12 +172,25 @@ static gm_result_void_t stub_commit_read_blob(void *self, return gm_err_void(GM_ERROR(GM_ERR_NOT_IMPLEMENTED, "test stub")); } +/** + * Free memory backing a blob buffer. + * + * @param data Pointer to the blob buffer to free. + * @param size Size of the blob buffer in bytes (unused by this implementation). + */ static void blob_dispose(void *self, uint8_t *data, size_t size) { (void)self; (void)size; free(data); } +/** + * Stub implementation that attempts to read a commit message but always fails and clears the output pointer. + * + * @param commit_oid Commit OID to read; ignored by this test stub. + * @param out_message Pointer to receive the commit message; if non-NULL, set to NULL. + * @returns An error indicating the operation is not implemented (`GM_ERR_NOT_IMPLEMENTED`) wrapped in a `gm_result_void_t`. + */ static gm_result_void_t stub_commit_read_message(void *self, const gm_oid_t *commit_oid, char **out_message) { @@ -133,11 +202,21 @@ static gm_result_void_t stub_commit_read_message(void *self, return gm_err_void(GM_ERROR(GM_ERR_NOT_IMPLEMENTED, "test stub")); } +/** + * Free a heap-allocated commit message. + * + * @param message Pointer to a heap-allocated NUL-terminated commit message to free; may be NULL. + */ static void stub_commit_message_dispose(void *self, char *message) { (void)self; free(message); } +/** + * Test stub for walking commits that always reports the operation as not implemented. + * + * @returns An error result with `GM_ERR_NOT_IMPLEMENTED`. + */ static gm_result_void_t stub_walk_commits(void *self, const char *ref_name, gm_git_commit_visit_cb visit_callback, void *userdata) { @@ -148,6 +227,17 @@ static gm_result_void_t stub_walk_commits(void *self, const char *ref_name, return gm_err_void(GM_ERROR(GM_ERR_NOT_IMPLEMENTED, "test stub")); } +/** + * Stub implementation of commit tree size retrieval for tests. + * + * If `out_size_bytes` is non-NULL, it is set to 0. The function always + * returns an error result indicating the operation is not implemented. + * + * @param self Unused stub instance pointer. + * @param commit_oid Unused commit OID. + * @param out_size_bytes If non-NULL, receives 0. + * @returns A gm_result_void_t containing `GM_ERR_NOT_IMPLEMENTED`. + */ static gm_result_void_t stub_commit_tree_size(void *self, const gm_oid_t *commit_oid, uint64_t *out_size_bytes) { @@ -159,6 +249,16 @@ static gm_result_void_t stub_commit_tree_size(void *self, return gm_err_void(GM_ERROR(GM_ERR_NOT_IMPLEMENTED, "test stub")); } +/** + * Test stub for creating a commit in the repository port. + * + * This implementation does not create a commit and always returns a not-implemented error. + * + * @param self Pointer to the repository port instance (unused). + * @param spec Specification of the commit to create (unused). + * @param out_commit_oid Output OID for the created commit (unused). + * @returns A gm_result_void_t representing `GM_ERR_NOT_IMPLEMENTED`. + */ static gm_result_void_t stub_commit_create(void *self, const gm_git_commit_spec_t *spec, gm_oid_t *out_commit_oid) { @@ -168,6 +268,11 @@ static gm_result_void_t stub_commit_create(void *self, return gm_err_void(GM_ERROR(GM_ERR_NOT_IMPLEMENTED, "test stub")); } +/** + * Stub implementation of a reference update used by tests that always reports not implemented. + * + * @returns A `gm_result_void_t` representing an error with code `GM_ERR_NOT_IMPLEMENTED` and message "test stub". + */ static gm_result_void_t stub_reference_update( void *self, const gm_git_reference_update_spec_t *spec) { (void)self; @@ -175,6 +280,14 @@ static gm_result_void_t stub_reference_update( return gm_err_void(GM_ERROR(GM_ERR_NOT_IMPLEMENTED, "test stub")); } +/** + * Stub that would resolve the blob OID for `path` at HEAD in test repository ports. + * + * @param self Pointer to the repository port instance (unused). + * @param path Path of the blob to resolve. + * @param out_blob_oid Output pointer to receive the blob OID when resolution succeeds. + * @returns A `gm_result_void_t` error value indicating not implemented (`GM_ERR_NOT_IMPLEMENTED`) for this test stub. + */ static gm_result_void_t stub_resolve_blob_at_head(void *self, const char *path, gm_oid_t *out_blob_oid) { (void)self; @@ -183,6 +296,11 @@ static gm_result_void_t stub_resolve_blob_at_head(void *self, const char *path, return gm_err_void(GM_ERROR(GM_ERR_NOT_IMPLEMENTED, "test stub")); } +/** + * Test stub that intentionally does not resolve a blob at a specific commit. + * + * @returns An error result with code GM_ERR_NOT_IMPLEMENTED indicating the operation is not implemented in the test stub. + */ static gm_result_void_t stub_resolve_blob_at_commit(void *self, const gm_oid_t *commit_oid, const char *path, @@ -194,6 +312,16 @@ static gm_result_void_t stub_resolve_blob_at_commit(void *self, return gm_err_void(GM_ERROR(GM_ERR_NOT_IMPLEMENTED, "test stub")); } +/** + * Stub that reports a commit has zero parents and indicates the operation is not implemented. + * + * If `out_parent_count` is non-NULL, it is set to 0 to indicate no parents. + * + * @param self Opaque repository port instance (unused). + * @param commit_oid OID of the commit to query (unused). + * @param out_parent_count Pointer to receive the parent count; set to 0 if non-NULL. + * @returns An error result indicating the function is not implemented (`GM_ERR_NOT_IMPLEMENTED`). + */ static gm_result_void_t stub_commit_parent_count(void *self, const gm_oid_t *commit_oid, size_t *out_parent_count) { @@ -224,17 +352,40 @@ static const gm_git_repository_port_vtbl_t TEST_PORT_VTBL = { .commit_parent_count = stub_commit_parent_count, }; +/** + * Prepare a test_git_repo_port_t for use by zeroing it and configuring its repository port vtable and self pointer. + * @param stub Pointer to the test stub to initialize. + */ static void init_stub(test_git_repo_port_t *stub) { gm_memset_safe(stub, sizeof(*stub), 0, sizeof(*stub)); stub->port.vtbl = &TEST_PORT_VTBL; stub->port.self = stub; } +/** + * Initialize `oid` from a hexadecimal string and abort on failure. + * + * @param oid Pointer to the OID to be populated. + * @param hex NUL-terminated hexadecimal string representation of the OID. + */ static void set_oid_from_hex(gm_oid_t *oid, const char *hex) { int rc = gm_oid_from_hex(oid, hex); assert(rc == GM_OK); } +/** + * Initialize a git reference tip structure with the given OID hex, commit time, and flags. + * + * Populates the provided gm_git_reference_tip_t by zeroing it and setting has_target and commit_time. + * If `zero_binary` is false and `hex` is non-NULL, the binary OID is parsed from `hex` and stored. + * If `hex` is non-NULL, its characters are copied into `tip->oid_hex` and NUL-terminated (truncated if necessary). + * + * @param tip Pointer to the tip structure to initialize. + * @param hex Hexadecimal string representation of the OID to store or copy; may be NULL. + * @param commit_time Commit timestamp to assign to the tip. + * @param has_target Whether the tip has a target reference. + * @param zero_binary If true, do not populate the binary OID even if `hex` is provided. + */ static void set_tip(gm_git_reference_tip_t *tip, const char *hex, uint64_t commit_time, bool has_target, bool zero_binary) { gm_memset_safe(tip, sizeof(*tip), 0, sizeof(*tip)); @@ -253,6 +404,16 @@ static void set_tip(gm_git_reference_tip_t *tip, const char *hex, } } +/** + * Fill a buffer with a repeated character and ensure null-termination. + * + * Writes `digit` into each of the first `buffer_len - 1` bytes and sets the + * final byte to the NUL terminator (`'\0'`). + * + * @param buffer Pointer to the destination buffer. + * @param buffer_len Total size of `buffer` in bytes; must be at least 1. + * @param digit Character to repeat throughout the buffer (except the terminator). + */ static void fill_hex(char *buffer, size_t buffer_len, char digit) { for (size_t i = 0; i + 1U < buffer_len; ++i) { buffer[i] = digit; @@ -260,10 +421,27 @@ static void fill_hex(char *buffer, size_t buffer_len, char digit) { buffer[buffer_len - 1U] = '\0'; } +/** + * Reset the journal tip sequence index to the beginning. + * + * This sets the test repository port's journal_tip_index to 0 so subsequent + * journal tip retrievals start from the first entry. + * + * @param stub Test repository port whose journal sequence will be reset. + */ static void reset_journal_sequence(test_git_repo_port_t *stub) { stub->journal_tip_index = 0U; } +/** + * Run unit tests that validate strict equality behavior of the cache check. + * + * Executes four scenarios that exercise gm_cache_is_stale with combinations of + * binary OID presence and legacy hex values to verify OID-first equality and + * hex-string fallback behavior. + * + * @returns 0 on success; a non-zero result (via failed assertion or abort) on failure. + */ int main(void) { printf("test_cache_strict_equality... "); diff --git a/core/tests/unit/test_journal_mixed_cbor.c b/core/tests/unit/test_journal_mixed_cbor.c index 9ac9fb12..b6d412e4 100644 --- a/core/tests/unit/test_journal_mixed_cbor.c +++ b/core/tests/unit/test_journal_mixed_cbor.c @@ -29,6 +29,16 @@ typedef struct { gm_edge_attributed_t last; } attr_ctx_t; +/** + * Capture a basic edge into a basic_ctx_t by copying the provided edge and + * incrementing the context's count. + * + * @param edge Pointer to the basic edge to capture. + * @param ud Pointer to a basic_ctx_t where the edge will be stored (last) + * and the count incremented. + * @returns `GM_OK` on success, `GM_ERR_INVALID_ARGUMENT` if `edge` or `ud` is NULL, + * or another `GM_*` error code propagated from the copy operation. + */ static int capture_basic_cb(const gm_edge_t *edge, void *ud) { if (edge == NULL || ud == NULL) { return GM_ERR_INVALID_ARGUMENT; @@ -43,6 +53,13 @@ static int capture_basic_cb(const gm_edge_t *edge, void *ud) { return GM_OK; } +/** + * Capture an attributed edge by copying it into the provided context and incrementing the count. + * + * @param edge Pointer to the attributed edge to capture; must not be NULL. + * @param ud Pointer to an attr_ctx_t that will receive the captured edge and have its count incremented; must not be NULL. + * @returns `GM_OK` on success, `GM_ERR_INVALID_ARGUMENT` if `edge` or `ud` is NULL, or an error code returned from the underlying copy operation. + */ static int capture_attr_cb(const gm_edge_attributed_t *edge, void *ud) { if (edge == NULL || ud == NULL) { return GM_ERR_INVALID_ARGUMENT; @@ -57,6 +74,13 @@ static int capture_attr_cb(const gm_edge_attributed_t *edge, void *ud) { return GM_OK; } +/** + * Run the mixed-CBOR journal integration test: create a temporary Git repository, + * write a commit containing one basic and one attributed CBOR-encoded edge payload, + * read them back, and verify their source/target OIDs match the generated values. + * + * @returns `0` on success, non-zero on failure. + */ int main(void) { printf("test_journal_mixed_cbor... "); git_libgit2_init(); From fff961fbe14ab977dd0e8b5e5101de4d808cb454 Mon Sep 17 00:00:00 2001 From: "P.R. PhiedBach" Date: Mon, 29 Sep 2025 16:05:59 +0000 Subject: [PATCH 2/2] opus(PR#175): seed rehearsal score (9b839ca3617b018dd970b785e650faed3fe15ca8) --- ...b839ca3617b018dd970b785e650faed3fe15ca8.md | 50 +++++++++++++++++++ 1 file changed, 50 insertions(+) create mode 100644 docs/code-reviews/PR175/9b839ca3617b018dd970b785e650faed3fe15ca8.md diff --git a/docs/code-reviews/PR175/9b839ca3617b018dd970b785e650faed3fe15ca8.md b/docs/code-reviews/PR175/9b839ca3617b018dd970b785e650faed3fe15ca8.md new file mode 100644 index 00000000..e3fffbd2 --- /dev/null +++ b/docs/code-reviews/PR175/9b839ca3617b018dd970b785e650faed3fe15ca8.md @@ -0,0 +1,50 @@ +--- +title: 9b839ca3617b018dd970b785e650faed3fe15ca8.md +description: Preserved review artifacts and rationale. +audience: [contributors] +domain: [quality] +tags: [review] +status: archive +--- + +# Code Review Feedback + +| Date | Agent | SHA | Branch | PR | +|------|-------|-----|--------|----| +| 2025-09-29 | CodeRabbit (and reviewers) | `9b839ca3617b018dd970b785e650faed3fe15ca8` | [coderabbitai/docstrings/e2eb59c](https://github.com/neuroglyph/git-mind/tree/coderabbitai/docstrings/e2eb59c "neuroglyph/git-mind:coderabbitai/docstrings/e2eb59c") | [PR#175](https://github.com/neuroglyph/git-mind/pull/175) | + +## CODE REVIEW FEEDBACK + +### General comment — coderabbitai[bot] + +```text + + + +> [!IMPORTANT] +> ## Review skipped +> +> CodeRabbit bot authored PR detected. +> +> To trigger a single review, invoke the `@coderabbitai review` command. +> +> You can disable this status message by setting the `reviews.review_status` to `false` in the CodeRabbit configuration file. + + + + + + +--- + + + +Comment `@coderabbitai help` to get the list of available commands and usage tips. + + +``` + +_Meta_: https://github.com/neuroglyph/git-mind/pull/175#issuecomment-3347845166 + +{response} +