From bea6ab6df56cc261027e3e67c56865b52701e617700d0acf927edcbf879a52ba Mon Sep 17 00:00:00 2001 From: "jabber.developer" Date: Wed, 29 Apr 2026 12:15:57 +0000 Subject: [PATCH] Add file structure --- file-structure.md | 112 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 112 insertions(+) create mode 100644 file-structure.md diff --git a/file-structure.md b/file-structure.md new file mode 100644 index 0000000..5d4b3a6 --- /dev/null +++ b/file-structure.md @@ -0,0 +1,112 @@ +## CProof Project Structure (for skill context) + +**CProof** is a terminal-based XMPP (chat) client written in C. It uses autotools for building and cmocka for unit testing. CProof is a fork of Profanity, renaming is WIP. + +### Build System +- `configure.ac` / `Makefile.am` - Autotools build configuration +- `autogen.sh` - Script to generate configure scripts +- `configure-debug` - Debug build helper +- `tests/prof_cmocka.h` - Test framework header (cmocka wrapper) + +### Source Directory (`src/`) + +| Directory | Purpose | +|-----------|---------| +| `src/ai/` | AI client implementation (`ai_client.c/h`) - OpenAI/Perplexity provider support | +| `src/command/` | Command handling (`cmd_ac.c/h` - autocomplete, `cmd_defs.c/h` - command definitions, `cmd_funcs.c/h` - command implementations) | +| `src/config/` | Configuration management (accounts, preferences, themes, colors, CA certs, scripts) | +| `src/event/` | Event handling (client events, server events, common) | +| `src/omemo/` | OMEMO encryption (crypto, store) | +| `src/otr/` | OTR encryption (`otr.c/h`, `otrlib.c/h`, `otrlibv4.c`) | +| `src/pgp/` | PGP/OpenPGP integration (`gpg.c/h`, `ox.c/h`) | +| `src/plugins/` | Plugin system (C API, Python API, autocompleters, callbacks, disco, settings, themes) | +| `src/tools/` | Utility functions (autocomplete, parser, clipboard, editor, HTTP download/upload, bookmark ignore) | +| `src/ui/` | User interface (buffers, windows, input, chat/muc/console windows, statusbar, tray, window management) | +| `src/xmpp/` | XMPP protocol layer (connection, roster, muc, presence, message, stanza, vcard, session, JID, capabilities, OMEMO, Ox, blocking, bookmark, chat state, avatar) | + +**Key files at `src/` root:** +- `main.c` - Entry point +- `profanity.c` - Application initialization/shutdown +- `common.h` - Common types/macros (including `auto_gchar` for memory management) +- `database.c` - Database layer +- `chatlog.c` - Chat log handling +- `log.c` - Logging + +### Tests Directory (`tests/`) + +| Directory | Purpose | +|-----------|---------| +| `tests/functionaltests/` | Integration tests (requires running CProof instance) | +| `tests/unittests/` | Unit tests (cmocka-based, run via `make check`) | + +**Unit test structure:** +- `tests/unittests/unittests.c` - Test runner (registers all tests) +- `tests/unittests/test_*.c/h` - Test files paired with headers +- `tests/unittests/helpers.c/h` - Test utilities +- `tests/unittests//stub_*.c` - Stub implementations for dependencies + +**Stub directories:** +- `unittests/ai/stub_ai_client.c` - AI client stubs +- `unittests/config/stub_accounts.c`, `stub_cafile.c` +- `unittests/database/stub_database.c` +- `unittests/log/stub_log.c` +- `unittests/omemo/stub_omemo.c` +- `unittests/otr/stub_otr.c` +- `unittests/pgp/stub_gpg.c`, `stub_ox.c` +- `unittests/tools/stub_*.c` +- `unittests/ui/stub_ai.c`, `stub_ui.c`, `stub_vcardwin.c` +- `unittests/xmpp/stub_*.c` + +### Key Patterns + +**Memory Management:** +- Uses `auto_gchar` macro (from `common.h`) for automatic GString/GString cleanup +- `g_free()`, `g_list_free_full()`, `g_hash_table_destroy()` for manual cleanup +- `FREE_SET_NULL()` / `GFREE_SET_NULL()` macros + +**Autocomplete System:** +- `Autocomplete` type (GList-based) defined in `tools/autocomplete.h` +- Functions: `autocomplete_new()`, `autocomplete_add()`, `autocomplete_complete()`, `autocomplete_free()` +- `autocomplete_param_with_ac()` - Complete using an Autocomplete object +- `autocomplete_param_with_func()` - Complete using a callback function +- `_autocomplete_param_common()` - Internal helper + +**Command System:** +- Commands defined in `cmd_defs.c` with `CMD_MAINFUNC()` and `CMD_TAGS()` macros +- Autocomplete registered in `cmd_ac.c` via `g_hash_table_insert(ac_funcs, "/cmd", _cmd_autocomplete)` +- `parse_args()` from `tools/parser.c` splits input into args array + +**Testing Patterns:** +- Use `will_return(func, value)` before calling `func()` to mock return values +- Use `expect_string()` for struct field verification +- Setup/teardown via `cmocka_unit_test_setup_teardown(test_func, setup, teardown)`, centralized in unittests.c +- Mock `connection_get_status()` with `will_return(connection_get_status, JABBER_CONNECTED)` if connection is needed + +### Current Work Context + +The `/ai` command autocomplete was recently added with: +- `ai_subcommands_ac` - Top-level subcommands: set, remove, start, clear, correct, providers +- `ai_set_subcommands_ac` - Set subcommands: provider, token, org +- `ai_remove_subcommands_ac` - Remove subcommands: provider +- `ai_providers_find()` - Provider name autocomplete callback (stateless, no `_last_provider_match`) +- Tests in `tests/unittests/test_ai_client.c` and `tests/unittests/test_ai_client.h` + +## Full List of `auto_` Macros (Automatic Memory Management) + +These macros use GCC's `__cleanup__` attribute to automatically free/close resources when they go out of scope. + +| Macro | Type | Cleanup Function | Description | +|-------|------|-----------------|-------------| +| `auto_gchar` | `gchar*` | `auto_free_gchar()` | Automatically frees a GLib character string | +| `auto_gcharv` | `gchar**` | `auto_free_gcharv()` | Automatically frees a GLib character string array (e.g., from `g_strsplit`) | +| `auto_char` | `char*` | `auto_free_char()` | Automatically frees a standard C string (from `strdup`) | +| `auto_guchar` | `guchar*` | `auto_free_guchar()` | Automatically frees a GLib unsigned char string (e.g., base64 decoded) | +| `auto_gfd` | `gint*` | `auto_close_gfd()` | Automatically closes a GFileDescriptor | +| `auto_FILE` | `FILE*` | `auto_close_FILE()` | Automatically closes a FILE stream | +| `auto_jid` | `Jid*` | `jid_auto_destroy()` | Automatically frees a Jid struct (defined only in `src/xmpp/jid.h`) | + +**Example usage:** +```c +auto_gchar gchar* myString = g_strdup("Hello, world!"); +// myString is automatically freed when scope exits +``` -- 2.49.1