374 lines
28 KiB
Markdown
374 lines
28 KiB
Markdown
# Convention Cleanup + Documentation Repair Implementation Plan
|
|
|
|
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
|
|
|
|
**Goal:** Bring the codebase into compliance with `CLAUDE.md`'s own stated rules that the audit found violated — 110 `#[allow(...)]` lint-bypass attributes (10 of them silencing `dead_code`, which the workspace `Cargo.toml` explicitly `deny`s), a custom error type where only `anyhow` is supposed to be used, small doc-comment gaps — and repair the five `docs/CODEMAPS/*.md` files plus `CLAUDE.md` itself, which reference pre-workspace-migration paths that no longer exist.
|
|
|
|
**Architecture:** No structural changes to running code beyond what's needed to satisfy the lints without suppressing them. Documentation tasks are pure text corrections against the now-accurate `crates/` layout (this plan should run **after** the other four plans in this series, since they change many of the exact file paths the docs need to describe correctly).
|
|
|
|
**Tech Stack:** Rust, Markdown.
|
|
|
|
## Global Constraints
|
|
|
|
- No **new** `#[allow(...)]` may be introduced by this plan's own changes.
|
|
- Every dead-code removal must be verified by letting the compiler/clippy confirm the item has zero remaining callers — never delete on assumption.
|
|
- Tests are inline `#[cfg(test)] mod tests`.
|
|
- Run `cargo test --workspace` and `cargo clippy --workspace --all-targets -- -D warnings` after each task.
|
|
- **Run this plan last**, after `2026-07-16-security-quickfixes.md`, `2026-07-16-oauth-session-iam-wiring.md`, `2026-07-16-cms-settings-appconfig-memory-editlog-wiring.md`, `2026-07-16-cms-conversation-blob-wiring.md`, and `2026-07-16-middleware-axum-server.md` — the documentation tasks (Task 6) describe the *end state* of all five, and several files this plan touches for lint cleanup (`app/runtime/actions/mod.rs`, `app/runtime/context/*.rs`) are also touched by those plans.
|
|
|
|
---
|
|
|
|
### Task 1: Delete the unused custom `Error` type in `zesdex-utils`
|
|
|
|
**Context:** `crates/zesdex-utils/src/error.rs` defines a hand-rolled `pub enum Error` + `impl std::error::Error` + a `Result<T>` alias, directly contradicting CLAUDE.md's "anyhow::Result and anyhow::bail! throughout... No custom error types" rule. Confirmed via workspace-wide grep: **zero call sites reference it outside the file itself** — it's simply dead code, not something anything depends on. `thiserror` is declared as a `zesdex-utils` dependency but never imported anywhere in the crate either.
|
|
|
|
**Files:**
|
|
- Delete: `crates/zesdex-utils/src/error.rs`
|
|
- Modify: `crates/zesdex-utils/src/lib.rs` (remove `pub mod error;`)
|
|
- Modify: `crates/zesdex-utils/Cargo.toml` (remove the unused `thiserror` dependency)
|
|
|
|
**Interfaces:** none — pure deletion.
|
|
|
|
- [ ] **Step 1: Verify zero remaining references**
|
|
|
|
Run: `grep -rln "zesdex_utils::error\|zesdex_utils::Error\|utils::error::" crates --include='*.rs'`
|
|
Expected: only `crates/zesdex-utils/src/error.rs` itself (or no output once the file is deleted).
|
|
|
|
- [ ] **Step 2: Delete the file**
|
|
|
|
```bash
|
|
git rm crates/zesdex-utils/src/error.rs
|
|
```
|
|
|
|
- [ ] **Step 3: Remove the module declaration**
|
|
|
|
In `crates/zesdex-utils/src/lib.rs`, remove:
|
|
```rust
|
|
pub mod error;
|
|
```
|
|
|
|
- [ ] **Step 4: Remove the unused `thiserror` dependency**
|
|
|
|
In `crates/zesdex-utils/Cargo.toml`, remove:
|
|
```toml
|
|
thiserror = { workspace = true }
|
|
```
|
|
|
|
- [ ] **Step 5: Build and test**
|
|
|
|
Run: `cargo build --workspace && cargo test -p zesdex-utils`
|
|
Expected: no errors.
|
|
|
|
- [ ] **Step 6: Commit**
|
|
|
|
```bash
|
|
git add -A
|
|
git commit -m "chore(utils): hapus custom Error type yang tidak dipakai (melanggar aturan anyhow-only)"
|
|
```
|
|
|
|
---
|
|
|
|
### Task 2: Resolve the 10 `dead_code` allow-bypasses
|
|
|
|
**Context:** These directly contradict the workspace's own `dead_code = "deny"` lint. For each, remove the `#[allow(dead_code)]`/`#![allow(dead_code)]`, run the compiler, and act on its verdict: if genuinely unused, delete; if actually reachable through a path the lint can't see (e.g. only used in `#[cfg(test)]` or behind a feature), wire it into real production code instead of re-suppressing.
|
|
|
|
**Files:**
|
|
- `crates/zesdex-backend/src/app/runtime/context/dedup.rs:1`
|
|
- `crates/zesdex-backend/src/app/runtime/context/squash.rs:1`
|
|
- `crates/zesdex-backend/src/app/runtime/context/window.rs:1`
|
|
- `crates/zesdex-backend/src/app/runtime/context/tokens.rs:32`
|
|
- `crates/zesdex-backend/src/app/subagent/spawn.rs:44,51`
|
|
- `crates/zesdex-backend/src/app/state/misc.rs:409`
|
|
- `crates/zesdex-backend/src/model/agent_def/{global.rs,builtin.rs,session.rs}:1`
|
|
|
|
**Interfaces:** varies per site — resolved during the investigation step, not fixed in advance (this is a "read what the compiler says, then act" task, not a hand-wave — see Step 1 of each site).
|
|
|
|
- [ ] **Step 1: `dedup.rs`, `squash.rs`, `window.rs` (module-level)**
|
|
|
|
Remove the `#![allow(dead_code)]` line from each of the three files. Run: `cargo build -p zesdex-backend 2>&1 | grep -A3 "never used"`
|
|
|
|
For each item the compiler flags as unused: check whether it's covered by a test in the same file's `#[cfg(test)] mod tests` (a test-only user doesn't count as a real caller and doesn't justify keeping the item) — if the item has zero non-test callers, delete it; if grepping the item's name elsewhere in `crates/zesdex-backend/src` (outside the file and outside `#[cfg(test)]` blocks) turns up a real caller the compiler somehow didn't connect (e.g. it's `pub` and meant for a different module that has a typo'd import), fix the import instead of deleting.
|
|
|
|
- [ ] **Step 2: `tokens.rs:32` (`count_message_tokens`)**
|
|
|
|
Read the function and its context: `grep -n -B5 -A15 "fn count_message_tokens" crates/zesdex-backend/src/app/runtime/context/tokens.rs`
|
|
|
|
Remove `#[allow(dead_code)]`. Run: `cargo build -p zesdex-backend 2>&1 | grep -A3 "count_message_tokens"`. If genuinely unused, delete the function (and any now-orphaned helper it alone called). If it looks like it *should* be called from the context-window-shaping logic in the same module (a token-counting function not being used by the token-budget code would itself be a functional gap worth flagging, not just a lint issue) — check `window.rs`'s `resolve()` and any `shaping`/`dedup` call sites for where a token count is needed but computed some other way, and wire `count_message_tokens` in there if that's the case; otherwise delete.
|
|
|
|
- [ ] **Step 3: `spawn.rs:44,51` (`with_max_steps`, `with_temperature` builder methods)**
|
|
|
|
Read the full builder struct: `grep -n -B20 "fn with_max_steps" crates/zesdex-backend/src/app/subagent/spawn.rs`
|
|
|
|
Remove both `#[allow(dead_code)]` lines. Run: `cargo build -p zesdex-backend 2>&1 | grep -A3 "with_max_steps\|with_temperature"`.
|
|
|
|
These configure per-agent `max_steps`/`temperature` on a subagent-spawn builder — check every call site that constructs this builder (`grep -rn "AgentSpawnBuilder\|::new()" crates/zesdex-backend/src/app/subagent/` — use the builder's actual type name found in Step 3's read) to see whether any caller *should* be setting these (e.g. does `hive_mind.rs`'s node-spawning code hardcode a default that should instead come from `Settings`/`NodeDirective` and isn't?). If a real caller needs them, wire them in (this may surface an actual functional gap, not just unused code — document what you find). If truly no caller has a legitimate need for per-agent overrides today, delete both methods and their backing struct fields if those fields are then also unused.
|
|
|
|
- [ ] **Step 4: `state/misc.rs:409` (`api_context_length` field)**
|
|
|
|
Read the surrounding struct: `grep -n -B15 -A5 "api_context_length" crates/zesdex-backend/src/app/state/misc.rs`
|
|
|
|
Remove `#[allow(dead_code)]`. Run: `cargo build -p zesdex-backend 2>&1 | grep -A3 "api_context_length"`. Check whether the status bar (`view/status.rs`) or connectivity-check code (`spawn_api_connectivity_check` in `actions/mod.rs`) should be displaying/using the model's context length but currently isn't — if so, wire it in; if the field was superseded by `app_config.model_roles[...].context_window` (per the CMS wiring plan) and is now genuinely redundant, delete the field.
|
|
|
|
- [ ] **Step 5: `model/agent_def/{global.rs,builtin.rs,session.rs}` (module-level)**
|
|
|
|
Same procedure as Step 1: remove each `#![allow(dead_code)]`, build, and either delete unused items or wire in real callers based on what the compiler reports.
|
|
|
|
- [ ] **Step 6: Full workspace build and test after all 10 sites are resolved**
|
|
|
|
Run: `cargo build --workspace && cargo test --workspace`
|
|
Expected: no errors, no `dead_code` warnings anywhere (the workspace `deny` will turn any remaining one into a hard build failure, which is the actual verification that every site was genuinely resolved).
|
|
|
|
- [ ] **Step 7: Commit**
|
|
|
|
```bash
|
|
git add -A
|
|
git commit -m "fix: hapus 10 allow(dead_code) - hapus kode mati atau sambungkan ke pemanggil nyata"
|
|
```
|
|
|
|
---
|
|
|
|
### Task 3: Resolve the 7 item-level clippy allows
|
|
|
|
**Files:**
|
|
- `crates/zesdex-backend/src/app/review/mod.rs:371` (`clippy::unnecessary_debug_formatting`)
|
|
- `crates/zesdex-backend/src/app/runtime/actions/mod.rs:1532` (`clippy::too_many_arguments`)
|
|
- `crates/zesdex-backend/src/app/runtime/actions/mod.rs:99,912` (`clippy::too_many_lines`, x2)
|
|
- `crates/zesdex-backend/src/app/subagent/engine.rs:326` (`clippy::too_many_lines`)
|
|
- `crates/zesdex-backend/src/view/markdown.rs:62` (`clippy::too_many_lines`)
|
|
- `crates/zesdex-backend/src/view/mod.rs:112` (`clippy::too_many_lines`)
|
|
|
|
**Interfaces:** none shared across sites — each is an independent, local fix.
|
|
|
|
- [ ] **Step 1: `clippy::unnecessary_debug_formatting` (easiest — do first)**
|
|
|
|
Read the flagged line: `grep -n -B3 -A3 "unnecessary_debug_formatting" crates/zesdex-backend/src/app/review/mod.rs`
|
|
|
|
Remove the `#[allow(clippy::unnecessary_debug_formatting)]` line. Run: `cargo clippy -p zesdex-backend 2>&1 | grep -A5 "unnecessary_debug_formatting"` to see the exact suggestion (clippy always proposes the fix inline — typically replacing a `format!("{:?}", x)` with `x.to_string()` or a `Display` impl call). Apply the suggested fix exactly.
|
|
|
|
- [ ] **Step 2: `clippy::too_many_arguments` on `actions/mod.rs:1532`**
|
|
|
|
Read the flagged function's full signature: `grep -n -B2 -A15 "clippy::too_many_arguments" crates/zesdex-backend/src/app/runtime/actions/mod.rs`
|
|
|
|
Bundle the excess parameters into a purpose-named struct (the standard fix for this lint). For example, if the function is `fn foo(a: X, b: Y, c: Z, d: W, ...) -> R`, introduce:
|
|
```rust
|
|
struct FooParams {
|
|
a: X,
|
|
b: Y,
|
|
c: Z,
|
|
d: W,
|
|
// ...
|
|
}
|
|
```
|
|
and change the signature to `fn foo(params: FooParams) -> R`, updating the function body to read `params.a`/`params.b`/etc., and updating the single call site to construct `FooParams { a, b, c, d, ... }`. (Exact field names/types depend on the actual signature found in this step's read — do not guess, use the literal parameter list.)
|
|
|
|
- [ ] **Step 3: `clippy::too_many_lines` — `actions/mod.rs:99` and `:912` (`run_agent_turn`)**
|
|
|
|
Read the full function: `grep -n -A 250 "^fn run_agent_turn" crates/zesdex-backend/src/app/runtime/actions/mod.rs | head -260`
|
|
|
|
This is the core per-turn agent loop — do not split it mechanically by line count; split along its own documented phase boundaries (the function's doc comment already describes them: "build system prompt → shape messages → call `chat_with_tools_streaming` → handle tool calls or unwrap final message → check unfinished todos → finalize"). Extract each phase that doesn't need to mutate more than 2-3 local variables into its own well-named private function, threading only what each phase actually needs as parameters (not the whole `TurnCtx` if a phase only reads one field). After extraction, re-add doc comments to each new function per CLAUDE.md's Code Documentation rules. Do this incrementally: extract one phase, build, test, commit; repeat rather than one giant rewrite, so a regression is easy to bisect.
|
|
|
|
Run after each extraction: `cargo build -p zesdex-backend && cargo test -p zesdex-backend`
|
|
|
|
Once the function is under clippy's threshold, remove the `#[allow(clippy::too_many_lines)]` at both flagged lines (99 and 912 — confirm both are on `run_agent_turn` or its immediate helper via the Step 1 grep; if they're on two different functions, repeat this decomposition process for each independently).
|
|
|
|
- [ ] **Step 4: `clippy::too_many_lines` — `app/subagent/engine.rs:326`**
|
|
|
|
Read the flagged function in full: `grep -n -B2 -A 200 "clippy::too_many_lines" crates/zesdex-backend/src/app/subagent/engine.rs | head -210`
|
|
|
|
Apply the same phase-based extraction approach as Step 3, scaled to this function's actual structure (read it first — do not assume it mirrors `run_agent_turn`'s shape).
|
|
|
|
- [ ] **Step 5: `clippy::too_many_lines` — `view/markdown.rs:62` and `view/mod.rs:112`**
|
|
|
|
Read both flagged functions in full first (`grep -n -A 150 "clippy::too_many_lines" crates/zesdex-backend/src/view/markdown.rs` and the equivalent for `view/mod.rs`). These are rendering functions — split along rendering sub-sections (e.g. one function per overlay/pane already rendered inline in a big `match`), extracting each `match` arm's body over some line-count threshold into its own `fn render_<thing>(f: &mut Frame, area: Rect, state: &AppStateRest)`-shaped helper, matching the existing `view/` module's established per-pane function naming convention (check `view/chat.rs`/`view/status.rs` for the naming pattern already in use and follow it).
|
|
|
|
- [ ] **Step 6: Full workspace verification**
|
|
|
|
Run: `cargo build --workspace && cargo test --workspace && cargo clippy --workspace --all-targets -- -D warnings`
|
|
Expected: all pass with zero `too_many_lines`/`too_many_arguments`/`unnecessary_debug_formatting` warnings and no remaining `#[allow]` for any of them.
|
|
|
|
- [ ] **Step 7: Commit each function's decomposition separately as you go (already instructed inline above) — final wrap-up commit if anything remains uncommitted**
|
|
|
|
```bash
|
|
git add -A
|
|
git commit -m "refactor: pecah fungsi yang melanggar clippy::too_many_lines/too_many_arguments, hapus allow-nya"
|
|
```
|
|
|
|
---
|
|
|
|
### Task 4: Reduce the 93 module-level cast-quad allows
|
|
|
|
**Context:** `#![allow(clippy::cast_possible_truncation, clippy::cast_sign_loss, clippy::cast_precision_loss, clippy::cast_possible_wrap)]` appears at the top of 93 files, evidently copy-pasted as workspace-wide boilerplate rather than justified per-file. This is the largest item in this plan by file count and — because it's the same mechanical recipe repeated 93 times — is best executed via `superpowers:subagent-driven-development` dispatching one subagent per file (or small batch of related files within the same crate) using the worked recipe below, rather than as one sequential task list here.
|
|
|
|
**Files:** all 93 listed in the audit's inventory (re-derive the authoritative current list before starting, since Tasks 1-3 and the other four plans in this series may have deleted or renamed some of them):
|
|
|
|
Run: `grep -rln "cast_possible_truncation, clippy::cast_sign_loss, clippy::cast_precision_loss, clippy::cast_possible_wrap" crates --include='*.rs'`
|
|
|
|
**Interfaces:** none shared — each file's fix is independent and self-contained.
|
|
|
|
- [ ] **Step 1: Worked example — pick one small, representative file first**
|
|
|
|
Read a small file from the list, e.g. `crates/zesdex-backend/src/app/mode/effort.rs` (confirm it's still in the current list from this task's Step-1 grep before using it as the example). Remove its `#![allow(clippy::cast_*...)]` line. Run:
|
|
|
|
Run: `cargo clippy -p zesdex-backend -- -D warnings 2>&1 | grep -B2 -A8 "effort.rs"`
|
|
|
|
For each flagged cast, apply the narrowest correct fix:
|
|
- `x as u32` where `x: usize` and the value is a count/length that can't realistically exceed `u32::MAX` → `u32::try_from(x).unwrap_or(u32::MAX)` (saturating, since these are almost always display/telemetry values where saturating is safe) or, if the call site already returns `Result`, `u32::try_from(x)?`.
|
|
- `x as i64` where `x: u64` timestamp (milliseconds since epoch) → these are safe until year 292471247, so `TryFrom` is technically correct but arguably pedantic; use `i64::try_from(x).unwrap_or(i64::MAX)` for consistency with the rule above rather than special-casing "this one's fine."
|
|
- `x as f32`/`x as f64` (precision loss) on values already known to fit (e.g. small counters) → keep the cast but make it explicit and document why it's lossless in context: `#[expect(clippy::cast_precision_loss, reason = "...")]` is still a bypass and NOT allowed by CLAUDE.md — instead, if the value truly can't lose precision (e.g. casting a `u8` to `f32`), the lint won't even fire once the blanket module-level allow is removed, since clippy's precision-loss lint only fires above the point where precision loss is actually possible for the source type; if it does fire, use the same `try_from`-then-`as` pattern, or restructure to avoid the float conversion entirely if it's just for display (`format!("{x}")` instead of casting to display as a percentage, etc.).
|
|
|
|
Run: `cargo build -p zesdex-backend && cargo test -p zesdex-backend`
|
|
Expected: no errors, no new warnings for this file.
|
|
|
|
- [ ] **Step 2: Commit the worked example**
|
|
|
|
```bash
|
|
git add crates/zesdex-backend/src/app/mode/effort.rs
|
|
git commit -m "fix: hapus allow cast-quad di effort.rs, ganti cast lossy dengan try_from"
|
|
```
|
|
|
|
- [ ] **Step 3: Dispatch the remaining files via subagent-driven-development**
|
|
|
|
For the remaining files from Step 1's grep (minus the one just fixed), use `superpowers:subagent-driven-development` with one task per file (or per small group of 3-5 files within the same module, where that reads more naturally), each task instructing: "remove the `#![allow(clippy::cast_*)]` header from `<file>`, run `cargo clippy -p <crate> -- -D warnings` scoped to that file, and fix every flagged cast using the recipe demonstrated in `2026-07-16-convention-cleanup-docs.md` Task 4 Step 1 (prefer `TryFrom`/`try_from` with a saturating fallback for lossy integer casts; restructure to avoid unnecessary float casts where the value is just being displayed)." Review each file's diff before merging — this is exactly the kind of large, repetitive, low-per-item-risk task the subagent-driven workflow is for.
|
|
|
|
- [ ] **Step 4: Final workspace-wide verification**
|
|
|
|
Run: `grep -rln "cast_possible_truncation, clippy::cast_sign_loss" crates --include='*.rs'`
|
|
Expected: no output (or, if a small number of files remain and are judged genuinely fine to leave as a future increment, that's a call for whoever is running this plan to make explicitly and document — not silently left as-is).
|
|
|
|
Run: `cargo build --workspace && cargo test --workspace && cargo clippy --workspace --all-targets -- -D warnings`
|
|
Expected: all pass.
|
|
|
|
---
|
|
|
|
### Task 5: Fill the remaining doc-comment gaps and remove dead scaffolding
|
|
|
|
**Files:**
|
|
- Modify: `crates/zesdex-backend/src/view/mod.rs` (lines 10-15 — `pub mod chat/markdown/sidebar/status/theme/workflow`, 5 of 7 missing doc comments)
|
|
- Modify: `crates/zesdex-backend/src/app/state/misc.rs` (line 340 `pub fn submit`, and the second gap the audit found around line 438)
|
|
- Delete: `/mnt/code/zesdex/tests/` (confirmed empty and untracked — safe to remove; re-verify emptiness before deleting since time has passed since the original audit)
|
|
|
|
**Interfaces:** none — doc comments and a directory deletion, no behavior change.
|
|
|
|
- [ ] **Step 1: Add doc comments to `view/mod.rs`'s module declarations**
|
|
|
|
Read the current lines: `grep -n -B1 "^pub mod" crates/zesdex-backend/src/view/mod.rs`
|
|
|
|
For each of `chat`, `markdown`, `sidebar`, `status`, `theme`, `workflow` that lacks a one-line doc comment above it, add one describing what that view submodule renders — e.g.:
|
|
|
|
```rust
|
|
/// Chat transcript pane: renders the scrollback of user/assistant/tool messages.
|
|
pub mod chat;
|
|
/// Markdown-to-styled-text rendering for assistant message content.
|
|
pub mod markdown;
|
|
/// Session sidebar: file tree / workspace navigation pane.
|
|
pub mod sidebar;
|
|
/// Status bar: provider/model, token usage, connectivity indicator.
|
|
pub mod status;
|
|
/// Color theme definitions for the TUI.
|
|
pub mod theme;
|
|
/// Hive-mind workflow panel: live node progress display.
|
|
pub mod workflow;
|
|
```
|
|
|
|
(Read each module's actual top-of-file doc comment first — `head -5 crates/zesdex-backend/src/view/{chat,markdown,sidebar,status,theme,workflow}.rs` — and base the one-liner on what that file's own doc comment says, rather than guessing, so the two stay consistent.)
|
|
|
|
- [ ] **Step 2: Add doc comments to the two flagged functions in `state/misc.rs`**
|
|
|
|
Read both: `grep -n -B2 -A8 "pub fn submit" crates/zesdex-backend/src/app/state/misc.rs` and the second flagged line (re-locate it — the original audit found it around line 438, but Task 2's dead-code cleanup on this same file may have shifted line numbers; search for the nearest undocumented `pub fn` instead of trusting the stale line number).
|
|
|
|
Add a doc comment to `submit` describing what it does (flow: clone the input buffer as the result, push to history if non-empty and not a duplicate of the last entry, persist history to disk if a history file is configured; return the submitted text) following CLAUDE.md's What/Flow/Why/Return structure, and do the same for the second flagged function once located.
|
|
|
|
- [ ] **Step 3: Remove the empty `tests/` directory**
|
|
|
|
Run: `find /mnt/code/zesdex/tests -mindepth 1` to confirm it's still empty.
|
|
Expected: no output.
|
|
|
|
If confirmed empty:
|
|
```bash
|
|
rmdir /mnt/code/zesdex/tests
|
|
```
|
|
|
|
(Use `rmdir`, not `rm -rf` — it only succeeds if the directory is genuinely empty, which is the safety property we want here.)
|
|
|
|
- [ ] **Step 4: Build and verify**
|
|
|
|
Run: `cargo build --workspace && cargo doc --workspace --no-deps 2>&1 | grep -i warn`
|
|
Expected: no new warnings from `cargo doc` (missing-docs isn't a workspace lint here, but this is a quick sanity pass).
|
|
|
|
- [ ] **Step 5: Commit**
|
|
|
|
```bash
|
|
git add crates/zesdex-backend/src/view/mod.rs crates/zesdex-backend/src/app/state/misc.rs
|
|
git rm -r --cached tests 2>/dev/null || true
|
|
git commit -m "docs: lengkapi doc comment view/mod.rs & state/misc.rs, hapus dir tests/ kosong"
|
|
```
|
|
|
|
---
|
|
|
|
### Task 6: Repair `docs/CODEMAPS/*.md` and `CLAUDE.md` to match the post-migration + post-wiring layout
|
|
|
|
**Context:** All five CODEMAPS files and CLAUDE.md itself reference pre-workspace-migration paths (`src/main.rs` instead of `crates/zesdex-backend/src/main.rs`, etc.), and `dependencies.md` describes a monolithic-crate dependency list that predates the workspace split entirely. Run this task **last**, after the other four plans in this series have landed, since many paths this task documents (OAuth location, Settings/AppConfig/Memory/EditLog/Conversation persistence, the new HTTP bridge) only exist once those plans are applied.
|
|
|
|
**Files:**
|
|
- Modify: `docs/CODEMAPS/architecture.md`
|
|
- Modify: `docs/CODEMAPS/backend.md`
|
|
- Modify: `docs/CODEMAPS/frontend.md`
|
|
- Modify: `docs/CODEMAPS/data.md`
|
|
- Modify: `docs/CODEMAPS/dependencies.md`
|
|
- Modify: `/mnt/code/zesdex/CLAUDE.md`
|
|
|
|
**Interfaces:** none — documentation only.
|
|
|
|
- [ ] **Step 1: Regenerate the authoritative file-path list**
|
|
|
|
Run: `find crates -name '*.rs' -not -path '*/target/*' | sort > /tmp/current-rust-files.txt` and keep this alongside the docs while editing, so every path cited is checked against a real file, not memory.
|
|
|
|
- [ ] **Step 2: Fix `architecture.md`**
|
|
|
|
For every code path mentioned (the Key Files table and inline references), prepend the correct crate prefix — e.g. `src/main.rs` → `crates/zesdex-backend/src/main.rs`, `src/app/harness.rs` → `crates/zesdex-backend/src/app/harness.rs`, and so on for every row. Cross-check each against `/tmp/current-rust-files.txt` from Step 1 before writing it. Update the ASCII system-layout diagram's "Tool/Subagents/Workflow" box if the OAuth rewiring (from `2026-07-16-oauth-session-iam-wiring.md`) or the HTTP bridge (from `2026-07-16-middleware-axum-server.md`) changed anything structurally significant enough to belong in a top-level diagram (the HTTP bridge, being an alternate IPC transport, is worth one added line: "IPC (Unix domain socket, or optional HTTP bridge via `--http-port`)").
|
|
|
|
- [ ] **Step 3: Fix `backend.md`**
|
|
|
|
Correct every path (`dto/provider/` → `crates/zesdex-dto/src/provider/`, `service/oauth/` → now `crates/zesdex-iam/src/{application/oauth_service.rs,infrastructure/oauth_loopback.rs}` per the OAuth rewiring plan, `src/ipc/*.rs` → `crates/zesdex-ipc/src/{protocol,conn,client,server}.rs`, etc.). Add a new subsection documenting the OAuth/session/CMS wiring: which crate now owns each concern (`zesdex-iam` for OAuth+session, `zesdex-cms` for Settings/AppConfig/Memory/EditLog/Conversation, `zesdex-middleware` for the optional HTTP bridge's auth/CORS/rate-limiting), replacing any stale description of the old monolithic `service::oauth`/`model::{settings,app_config,memory,edit_log,msglog}` modules (which this plan's sibling plans delete).
|
|
|
|
- [ ] **Step 4: Fix `frontend.md`**
|
|
|
|
Correct every `main.rs`/`controller/input.rs`/`view/*.rs`/`app/mode/*.rs` reference to include the `crates/zesdex-backend/src/` prefix.
|
|
|
|
- [ ] **Step 5: Fix `data.md`**
|
|
|
|
Correct `src/app/state/rest.rs` → `crates/zesdex-backend/src/app/state/rest.rs`. Replace the section describing `src/model/{settings,app_config,memory,edit_log}.rs` (all deleted by the CMS wiring plans) with a description of `zesdex-cms`'s repository-based persistence (`JsonSettingsRepository`, `JsonAppConfigRepository`, `MarkdownMemoryRepository`, `JsonlEditLogRepository`, `JsonConversationRepository`, `FileRewindBlobRepository`) and where each writes on disk. Replace the `msglog` SQLite description with the new `Conversation`/`conversation.json` + file-based rewind blob store description.
|
|
|
|
- [ ] **Step 6: Rewrite `dependencies.md`**
|
|
|
|
Replace the header claim ("23 Rust crates" per CLAUDE.md / "30+ direct" per this file's own header — pick neither, state the actual count) with an accurate summary: list all 9 internal workspace crates (`zesdex-entities`, `zesdex-utils`, `zesdex-dto`, `zesdex-ipc`, `zesdex-iam`, `zesdex-cms`, `zesdex-middleware`, `zesdex-libs`, `zesdex-backend`) with a one-line purpose each, then the external dependency list — regenerate this list from the actual `[workspace.dependencies]` table in the root `Cargo.toml` rather than editing the existing prose by hand:
|
|
|
|
Run: `grep -A100 "\[workspace.dependencies\]" Cargo.toml`
|
|
|
|
Explicitly call out the dependencies added by the workspace migration that the current doc omits entirely: `axum`, `tower`, `tower-http`, `argon2`, `jsonwebtoken`, `thiserror` (note: `thiserror` may be removed from the workspace entirely by Task 1 of this plan if `zesdex-utils` was its only consumer — check with `grep -rln "thiserror" crates --include='*.rs' crates/*/Cargo.toml` before listing it as a current dependency).
|
|
|
|
- [ ] **Step 7: Fix `CLAUDE.md`**
|
|
|
|
Update every path in the "Key Files"-equivalent references (`src/main.rs`, `src/app/harness.rs`, `src/app/subagent/division.rs`, `src/app/workflow/hive_mind.rs`, `src/tool/workflow.rs`, `src/app/workflow/docs.rs`, `src/view/workflow.rs`, `src/app/subagent/auto.rs`) to their `crates/zesdex-backend/src/...` equivalents. Update the "Shell safety" line per `2026-07-16-security-quickfixes.md` Task 1 Step 4 if that plan hasn't already been applied. Update the "No custom error types" line's context if useful (it's now fully true rather than aspirational, per this plan's Task 1). Add one line under "Key Patterns" noting the optional HTTP daemon transport if `2026-07-16-middleware-axum-server.md` has been applied: "**Daemon transports** — Unix domain socket (default) or, with `--http-port`, an axum HTTP bridge (`ipc_http.rs`) speaking the same `ClientRequest`/`DaemonFrame` protocol, gated by `zesdex-middleware`'s session-auth/CORS/rate-limit layers."
|
|
|
|
- [ ] **Step 8: Verify every path cited resolves to a real file**
|
|
|
|
Run a small verification script for each doc — for every backtick-quoted path matching `src/` or `crates/`, confirm it exists:
|
|
|
|
```bash
|
|
for f in docs/CODEMAPS/*.md CLAUDE.md; do
|
|
grep -oE '`[a-zA-Z0-9_/.-]+\.rs`' "$f" | tr -d '`' | while read -r path; do
|
|
[ -f "$path" ] || echo "MISSING in $f: $path"
|
|
done
|
|
done
|
|
```
|
|
|
|
Expected: no `MISSING` lines. Fix any that appear.
|
|
|
|
- [ ] **Step 9: Commit**
|
|
|
|
```bash
|
|
git add docs/CODEMAPS CLAUDE.md
|
|
git commit -m "docs: perbaiki path stale di CODEMAPS dan CLAUDE.md pasca migrasi workspace + wiring zesdex-iam/cms/middleware"
|
|
```
|