retoor/packfs
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Document every public function; fix a real gap the audit found

Browse Source 
Cross-checked every function declared in include/packfs.h against
nm -D libpackfs.so.0 as the starting point for a full documentation
pass, per the request to document literally everything rather than
just the parts already covered.

That check found a genuine bug, not just a documentation gap:
backend_pack_new was declared in the public header and named in
CLAUDE.md's architecture map, but never implemented in src/pack.c —
any caller would fail at link time. Implemented it as a standalone,
read-only `pack` Backend (every mutating call returns VFS_ERR_PERM,
consistent with concept.md Section 2.1 listing `pack` as its own
backend kind distinct from the overlay), covered it with a new test
case, and verified it under -fsanitize=undefined per CLAUDE.md's
sanitizer rule.

Added a doc comment to every previously-undocumented function and
struct field in packfs.h and internal.h (vfs_open/read/write/close/
stat/readdir/mkdir/unlink/rename, every upper_* structural/content
function, pfs_dir_*, pfs_fnv1a64, PackIndexEntry/Pack fields). Updated
README and CLAUDE.md to mention backend_pack_new and to stop gesturing
at zip/tar as though import/export exists.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01UqJpkdJ6Njnt1pw3CbghzB
This commit is contained in:
retoor
2026-09-14 05:54:52 +00:00
co-authored by Claude Sonnet 5
parent 72e3c900f2
commit 9fb5cf2d9a
6 changed files with 350 additions and 20 deletions
Download Patch File Download Diff File Expand all files Collapse all files
tests/test_pack_overlay.c
+31
View File
@@ -100,6 +100,37 @@ int main(void) {
backend_free(mem2);
vfs_free(v2);
/* --- standalone read-only pack backend (Section 2.1/3.1), no overlay --- */
Vfs *v4 = vfs_new();
int perr = 0;
Backend *ro = backend_pack_new(pack_path, &perr);
CHECK(ro != NULL);
CHECK_EQ_INT(vfs_mount(v4, "/", ro), VFS_OK);
f = vfs_open(v4, "/a.txt", VFS_O_RDONLY, &err);
CHECK(f != NULL);
memset(buf, 0, sizeof(buf));
CHECK_EQ_INT(vfs_read(f, buf, sizeof(buf)), 4);
CHECK_STR_EQ(buf, "ZZZZ");
CHECK_EQ_INT(vfs_close(f), VFS_OK);
/* read-only: every mutation is rejected, not silently absorbed */
CHECK_EQ_INT(vfs_mkdir(v4, "/nope"), VFS_ERR_PERM);
CHECK_EQ_INT(vfs_unlink(v4, "/a.txt"), VFS_ERR_PERM);
f = vfs_open(v4, "/new.txt", VFS_O_WRONLY | VFS_O_CREAT, &err);
CHECK(f == NULL);
CHECK_EQ_INT(err, VFS_ERR_PERM);
CHECK_EQ_INT(vfs_sync(v4, "/"), VFS_ERR_PERM);
VfsDir rdir;
CHECK_EQ_INT(vfs_readdir(v4, "/", &rdir), VFS_OK);
CHECK(rdir.count > 0);
vfs_dir_free(&rdir);
vfs_unmount(v4, "/");
backend_free(ro);
vfs_free(v4);
/* --- pack integrity validation (Section 7): a corrupted pack is rejected --- */
int fd = open(pack_path, O_RDWR);
CHECK(fd >= 0);