From a9957113354cbb773bab09f648b8d69ca27545b2 Mon Sep 17 00:00:00 2001 From: Scott Idem Date: Thu, 13 Nov 2025 14:24:05 -0500 Subject: [PATCH] Update TODO.md and GEMINI.md to reflect temporary rollback of ae_core_functions.ts and module-by-module refactoring plan. --- GEMINI.md | 26 ++++++++++++++++++++++++++ TODO.md | 45 +++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 71 insertions(+) diff --git a/GEMINI.md b/GEMINI.md index e1995534..0489fbef 100644 --- a/GEMINI.md +++ b/GEMINI.md @@ -27,3 +27,29 @@ The following directories are ignored for various operations (e.g., search, file - `build` - `node_modules` - `tests` + +--- + +## Refactoring Notes + +### `process_ae_obj__*_props()` Refactoring (2025-11-13) + +The `process_ae_obj__*_props()` family of functions, which are responsible for transforming API data for frontend use, have been refactored to standardize their structure and improve maintainability. + +The refactoring strategy involved creating a local, non-exported `_process_generic_props` helper function within each module (`ae_journals`, `ae_events`, `ae_archives`, `ae_posts`, `ae_core`). This approach was chosen to avoid altering the module import graph, which had previously caused a critical `InternalError: module record has unexpected status: New` in the SvelteKit development server when a shared utility file was introduced. + +**Key aspects of the refactoring:** + +* **In-file Generic Helper (`_process_generic_props`):** This function handles common data transformations: + * **`*_random` ID Aliasing:** It automatically iterates over object keys and creates a non-suffixed alias for any key ending in `_random` (e.g., `person_id_random` becomes `person_id`). This is crucial for client-side logic that expects standard ID fields. + * **`tmp_sort` Field Generation:** It creates a set of basic `tmp_sort` fields for client-side sorting. + +* **`specific_processor` Callback:** Module-specific logic is handled by a `specific_processor` callback function passed to the `_process_generic_props` helper. This allows for: + * **Unique `tmp_sort` Logic:** Modules can override the default `tmp_sort` fields with their own specific sorting requirements. + * **Content Processing:** Asynchronous operations like Markdown parsing (using `marked.parse`) are handled within the `specific_processor` for the relevant modules (e.g., `ae_journals__journal_entry.ts`). + * **Other Special Cases:** Any other module-specific data transformations are handled in this callback. + +* **`core__crud_generic.ts` Cleanup:** The generic CRUD functions in `src/lib/ae_core/core__crud_generic.ts` were simplified: + * The `process_ae_obj__props` function in this file was deprecated. + * All calls to `process_ae_obj__props` and `db_save_ae_obj_li__ae_obj` were removed from the generic CRUD functions (`load_ae_obj_id`, `load_ae_obj_li`, etc.). + * These functions are now responsible only for API interaction, delegating all data processing and caching to the module-specific functions that call them. This enforces a cleaner separation of concerns. diff --git a/TODO.md b/TODO.md index c67213f2..16e0927e 100644 --- a/TODO.md +++ b/TODO.md @@ -2,6 +2,36 @@ This is a list of tasks to be completed before the next event/show/conference. +--- + +## Codebase Standardization + +### 1. Naming Conventions +- [ ] **Goal:** Enforce a single, consistent naming standard across the entire codebase. +- [ ] **Files:** + - Logic: `ae___.ts` + - DB Definitions: `db_.ts` + - Svelte Stores: `ae__stores.ts` + - Consolidate helper files (e.g., `ae_core_functions.ts`) into the above files. +- [ ] **Functions & Variables:** + - Enforce `snake_case` for all function and variable names. + - Deprecate and remove `camelCase`. + - Deprecate and refactor ambiguous `handle_` prefixes. +- [ ] **Object & Property Naming:** + - Use singular nouns for objects and properties (e.g., `example.id`, not `examples.id`). +- [ ] **List Suffixes:** + - Use `_li` for simple, unordered arrays. + - Use `_kv` for key-value objects/maps. +- [ ] **Process:** + - Refactor one module at a time to ensure internal consistency before moving to the next. Start with `ae_core`. + - **Update 2025-11-13:** `ae_core_functions.ts` has been temporarily restored to resolve a critical issue. The refactoring of `process_ae_obj__*_props()` functions will now proceed module by module, ensuring stability at each step. + +### 2. Component Standardization +- [ ] **CodeMirror Migration:** Plan and execute the replacement of the `shad-editor` and potentially other text editors (like Tiptap) with `CodeMirror` to standardize rich text editing. +- [ ] **Component Review:** Audit third-party components to understand their conventions and isolate them from internal standards. + +--- + ## Priority Tasks (Easy & Quick) - [x] **Core:** Define `Account`, `Site`, and `Site_Domain` interfaces in new files under `src/lib/ae_core/`. @@ -27,6 +57,7 @@ These functions are frequently used and critical to the application's data flow. 3. **The `process_ae_obj__*_props()` family of functions** (e.g., `process_ae_obj__journal_props()` from `src/lib/ae_journals/ae_journals__journal.ts`) * **Why:** These functions transform API data for the frontend and are a common source of bugs and inconsistencies. * **Cleanup:** Standardize their structure across all modules, ensure they are pure functions, and add unit tests for correctness. + * **Update 2025-11-13 (Temporary Rollback):** The previous refactoring of these functions has been temporarily rolled back due to an `InternalError`. `ae_core_functions.ts` has been restored. The new plan is to refactor these functions module by module, ensuring stability at each step. The generic CRUD functions in `core__crud_generic.ts` were simplified to remove data processing and caching, delegating those responsibilities to the module-specific functions. The deprecated `process_ae_obj__props` function in that file was left in place but is no longer used by the generic CRUD functions. 4. **Usage of `liveQuery` from Dexie** * **Why:** `liveQuery` is powerful for reactive UIs, but current usage suggests complexity and potential issues. @@ -177,3 +208,17 @@ These functions are frequently used and critical to the application's data flow. ### Performance - [ ] **Live Queries:** Review the use of `liveQuery` throughout the module and optimize for performance, especially on pages with a large amount of data. - [ ] **Data Loading:** Implement more efficient data loading strategies to avoid fetching unnecessary data. + +--- + +## UI/UX Consistency + +- [ ] **Broad UI/UX Review:** Conduct a comprehensive review of UI elements across the application to ensure consistency. This includes, but is not limited to: + - Buttons (style, placement, wording) + - Lists (style, actions) + - Links vs. Buttons (correct semantic usage) + - Menus (style, options) + - Debug components and other developer-facing UI. + - **Wording:** Standardize the text used in common UI elements (e.g., "Save", "Cancel", "Delete", "Add New"). + - **Scope:** This should be done on a per-module basis to ensure local consistency, with a goal of achieving global consistency where possible. + - **Note on IDAA:** The `idaa` modules are semi-custom for a client and may have their own specific UI/UX requirements. Their consistency should be evaluated separately, keeping the client's needs in mind.