RuDS/CLEANUP.md

Cleanup Backlog

Findings from a repo-wide audit (2026-07-18) for over-engineering, dead code, and idiomatic-Rust issues beyond what clippy/rustfmt catch. Ordered by priority — the first item is a real bug, the rest are cleanup. Each item is self-contained.

Ground rules (from AGENTS.md): red/green TDD, run build + tests after each item, remove unused code instead of keeping it, verify behaviour against the allium specs in specs/ and the Elixir baseline in ../bDS2 when in doubt.

1. BUG: temp-file collision in atomic_write

crates/bds-core/src/util/atomic_write.rs uses path.with_extension("tmp"), which replaces the last extension. Sibling files that differ only in their final extension map to the same temp path:

• esmeralda.en.md → esmeralda.en.tmp
• esmeralda.en.meta → esmeralda.en.tmp

Concurrent writes (e.g. publishing writes post file + sidecars in parallel) can interleave on the shared temp file and corrupt or cross-write content. It also clobbers any real file named *.tmp.

Fix: append a unique suffix to the full filename instead of replacing the extension, e.g. format!("{}.{}.tmp", file_name, std::process::id()) or a counter/uuid. Add a regression test writing a.en.md and a.en.meta concurrently (or at least assert the two temp paths differ).

2. Parallel record-struct layer in the DB glue (~450 lines)

crates/bds-core/src/db/from_row.rs defines a *Record twin struct for all 12 tables plus hand-written From/TryFrom conversions in both directions. Most fields are copied 1:1; only a handful need conversion (status/kind enums, i32 bools, JSON string-lists).

Fix: implement diesel ToSql/FromSql (or serialize/deserialize wrappers) for PostStatus, TemplateKind, TemplateStatus, ScriptKind, ScriptStatus, NotificationEntity, NotificationAction, plus a newtype for JSON-serialized Vec<String> (tags/categories) and bool-as-i32, then derive Queryable/Selectable/Insertable/AsChangeset on the domain models in crates/bds-core/src/model/ directly. Delete the record structs and the convert/convert_all helpers. Keep behaviour identical: tags serialize as JSON arrays, unknown enum strings must still error, treat_none_as_null must be preserved.

3. Split the god file: bds-ui/src/app.rs (9,090 lines)

update() alone spans ~2,250 lines (line 982–3238). The fix pattern already exists in the same file: handle_tags_msg and handle_settings_msg delegate a message sub-enum to a dedicated handler.

Fix: apply the same pattern to the remaining domains — post editor, media editor, template/script editors, preview/embedded webview, AI actions, translation flows, sidebar/filtering. Move each handler group into its own module (e.g. crates/bds-ui/src/app/posts.rs), keeping Message routing thin. Pure refactor: no behaviour change, existing tests must stay green.

4. Dead task machinery in engine/task.rs (~130 lines)

Zero production call sites in the workspace for:

• ProgressThrottle (whole struct + its 2 tests) — its logic is already duplicated inside TaskManager::report_progress
• TaskProgress struct
• try_start
• submit_grouped and the group_id/group_name fields it fills (carried through TaskEntry and TaskSnapshot, never read by the UI)
• label(), message() accessors
• next_queued (test-only)

Fix: delete them and their tests.

Related wiring gap (do NOT delete, investigate): evict_expired() and is_cancelled() are also never called from production code. That means finished tasks are never evicted at runtime and cooperative cancellation never actually interrupts running work. Either wire them up in bds-ui/src/app.rs (evict on the task-snapshot refresh tick; check is_cancelled inside long-running engine loops) or confirm against the allium spec what the intended behaviour is.

5. Dead public functions (~250 lines)

Zero call sites anywhere in the workspace (verified by sweep):

• crates/bds-core/src/engine/validate_translations.rs: validate_translations — only validate_translations_with_progress is used
• crates/bds-core/src/engine/meta.rs: update_blog_languages, update_project_metadata
• crates/bds-core/src/db/queries/generated_file_hash.rs: delete_generated_file_hash, list_generated_file_hashes_by_project
• crates/bds-core/src/db/queries/post.rs: list_posts_by_project_limited
• crates/bds-core/src/db/queries/media.rs: list_media_by_project_limited
• crates/bds-core/src/db/queries/post_link.rs: list_post_backlinks, list_post_outlinks
• crates/bds-core/src/db/from_row.rs: notification_entity_to_str, notification_action_to_str

Fix: delete, along with any tests that exist only to exercise them.

Special case: crates/bds-core/src/db/fts.rs::search_media has only test callers. AGENTS.md requires functionality to be tied to UI — check the allium spec: if media search is specced, wire it into the UI; if not, delete.

6. Delete unused EngineContext

crates/bds-core/src/engine/context.rs — a "shared context passed to engine operations" that zero engine operations take (every engine fn takes conn/project_id/data_dir individually). Its only test asserts that struct fields hold assigned values.

Fix: delete the file, its pub use in crates/bds-core/src/engine/mod.rs.

7. Derive EngineError with thiserror

crates/bds-core/src/engine/error.rs hand-writes Display, Error::source, and four From impls (~85 lines). DatabaseError in crates/bds-core/src/db/connection.rs already uses #[derive(thiserror::Error)] — the crate is inconsistent.

Fix: convert EngineError to a thiserror derive (#[error(...)], #[from], #[source]). Keep the From<DatabaseError> mapping and the reqwest/serde_json/serde_yaml → Parse conversions (thiserror #[from] can't map two sources into one variant with .to_string(), so those three stay as small manual impls or become dedicated variants).

8. Single source of truth for status/kind enum strings

PostStatus ↔ string mapping exists three times:

1. serde #[serde(rename_all = "lowercase")] on the enum (crates/bds-core/src/model/post.rs)
2. post_status_to_str / post_status in crates/bds-core/src/db/from_row.rs
3. the serde_json::to_string(&status).trim_matches('"') hack in crates/bds-core/src/util/frontmatter.rs (PostFrontmatter::from_post, TranslationFrontmatter::from_translation)

Fix: give each enum (PostStatus, TemplateKind, TemplateStatus, ScriptKind, ScriptStatus) an as_str() + FromStr impl next to its definition, use it from the DB layer and frontmatter, delete the duplicates and the serde_json hack. (Combines well with item 2.)

9. Derive frontmatter deserialization (~120 lines)

crates/bds-core/src/util/frontmatter.rs: the four from_yaml impls each hand-roll near-identical get_str/get_string_list closures over serde_yaml::Value.

Fix: replace with #[derive(Deserialize)] + #[serde(rename_all = "camelCase")] structs and one shared deserialize_with helper for ISO-8601 → unix-ms timestamps. Preserve current lenient behaviour (numbers/bools coerced to strings where fields expect strings; missing optional fields default).

Do NOT touch the serialization side (to_yaml): it is deliberately hand-rolled for byte-identical golden output against the gray-matter format — the golden_output_* tests assert exact equality with fixture files.

10. Minor shrinks

• crates/bds-core/src/util/checksum.rs: replace the inline hex module with bytes.iter().map(|b| format!("{b:02x}")).collect::<String>(). (Correctly avoids adding a hex crate dep — keep it that way.)
• crates/bds-core/src/i18n/mod.rs: RENDER_KEYS hardcodes 34 keys that must be kept in sync with the .ftl catalogs by hand. Enumerate the parsed FluentResource entries of the English render catalog instead, so new keys can't be silently missed.
• crates/bds-core/src/i18n/mod.rs: locale_index can be locale as usize with explicit discriminants on UiLocale.

---

Test Suite Cleanup

Findings from a full test-suite review (2026-07-18). The suite is largely healthy: engine/query tests run against real in-memory SQLite, AI tests run the real HTTP client against a local TCP test server, golden-output tests pin byte-compatibility with the bDS2 baseline fixtures. No mock-object testing anti-pattern exists. The problems are hot-air tests (assertions the compiler already guarantees or that test a literal against itself) and duplication.

T1. Delete bds-ui/tests/app_smoke.rs entirely

Every test in the file is compile-time noise:

• message_variants_constructable, new_message_variants_constructable (~80 lines): construct Message enum variants and discard them — the compiler already guarantees this
• message_clone_works: tests #[derive(Clone)]
• bds_app_type_is_public: an inner function that is never called; purely a type assertion with no runtime assertion

The file's own header admits BdsApp::new() cannot be tested here. The real smoke coverage lives in app.rs's inline tests (which drive update() against a real in-memory DB via new_for_tests). Delete the file.

T2. Hot air in bds-ui/tests/m2_validation.rs

• toast_level_variants, toast_preserves_message: assert that a constructor stores its arguments. Delete.
• toast_ids_are_monotonically_increasing, fresh_toast_is_not_expired: duplicate the inline tests in crates/bds-ui/src/state/toast.rs (toast_ids_are_unique, fresh_toast_not_expired). Keep one location (suggest inline), delete the other.
• menu_actions_that_need_project / menu_actions_that_need_tab / menu_actions_gated_by_offline: their own comment admits they don't test the gating logic — they only re-verify i18n keys (already covered for ALL actions in menu_routing.rs::all_menu_actions_translate_in_all_locales) and then assert_eq!(array.len(), N) on the literal array declared five lines above. Delete. Real gap: the actual enable/disable rules in BdsApp::sync_menu_state (app.rs) are untested — write a test that drives the real method (or extract its decision logic into a testable function).
• accelerator_actions_match_spec: asserts a locally declared array has 15 elements and that i18n keys are non-empty; never touches the real accelerator registration in platform/menu.rs. Delete, or rewrite to inspect the actual menu construction.

T3. Hot air in bds-core/tests/spec_claims.rs

• remaining_value_specs_match contains assert_eq!(["en", "de", "fr", "it", "es"].len(), 5) — a literal tested against itself. Drop that line (the serde asserts around it are fine).
• slug_frozen_after_publish_semantics: the name promises the slug-freeze invariant; the body only asserts published_at is Some/None after insert (already covered by roundtrip tests elsewhere). Either write the real test — attempt a slug change on a published post through the engine API and assert it's rejected — or delete.

T4. Vacuous inline tests in bds-core/src/i18n/mod.rs

• ui_locale_is_independent_type: asserts "de" != "fr". Delete.
• translate_falls_back_to_english: identical call and assertion as translate_menu_labels, and it does NOT test fallback — the key it uses has a German translation. Replace with a key that exists only in en.ftl (that actually exercises add_resource_overriding fallback), or delete.
• detect_os_locale_does_not_panic: marginal smoke; keep or drop, zero cost.

T5. Tests that only exist to cover dead code

Deleted together with their subjects (see items 4–6 above):

• engine/task.rs: progress_throttle_initial_reports, progress_throttle_suppresses_rapid (test the dead ProgressThrottle)
• engine/context.rs: context_holds_references (asserts struct fields hold assigned values)
• engine/error.rs: display_variants, from_io_error become derive-testing once EngineError moves to thiserror; delete with item 7

T6. Change-detector test in bds-ui/tests/menu_routing.rs

menu_action_count_matches_spec asserts MenuAction::ALL.len() == 28. It must be hand-bumped on every menu change and only ever catches forgetting to update itself; the useful properties (every action has a key, keys unique, all locales translate) are covered by the other three tests in the file. Delete.

Explicitly fine (do not "clean up")

• tests/orm_boundary.rs, tests/i18n_completeness.rs, tests/packaging_assets.rs: lints-as-tests. They don't test runtime behaviour but mechanically enforce AGENTS.md rules (no raw SQL outside the backend boundary, no untranslated keys, packaging config integrity). Keep.
• fixture_readability.rs::fixture_database_files_are_not_modified_by_tests: meta-test guarding fixture integrity for the whole compat suite. Keep.
• m1_validation.rs: the per-field diff-detection matrix looks repetitive but each test pins one metadata-diff field required by the spec. Keep.
• AI engine tests spawn a real local TCP server — fake at the network boundary, real production client code exercised. This is the right pattern.
• util/timestamp.rs::now_is_recent looks trivial but guards milliseconds-vs-seconds confusion. Keep.

---

Explicitly out of scope

• crates/bds-cli being a stub: intentional, part of upcoming extensions.
• The hand-rolled YAML serialization in frontmatter.rs and sidecar.rs: required for byte-compatibility with the baseline output.