refactor: split major code smell hotspots

Author: ahavili

docs/superpowers/plans/2026-04-09-code-smell-remediation.md

@@ -0,0 +1,137 @@
+# Code Smell Remediation 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:** Reduce the highest-maintenance code smells in Grapha without changing user-visible behavior, starting with the broken Swift index-store config and then splitting the largest multi-responsibility modules into focused units.
+
+**Architecture:** Fix correctness first by replacing the dead process-global index-store toggle with explicit configuration flow through the extraction pipeline. Then perform bounded structural refactors in three areas: Swift tree-sitter enrichment, CLI orchestration, and SQLite persistence. Each phase should preserve behavior with targeted tests before any further decomposition.
+
+**Tech Stack:** Rust workspace, clap, rusqlite, rayon, existing `grapha_core` plugin/extraction pipeline, existing integration/unit tests with `assert_cmd`
+
+---
+
+## File Structure
+
+| File | Responsibility |
+|------|----------------|
+| Modify: `grapha/src/main.rs` | Current CLI entrypoint, pipeline orchestration, command dispatch, watch-mode server path |
+| Modify: `grapha/src/config.rs` | `swift.index_store` configuration source of truth |
+| Modify: `grapha-swift/src/lib.rs` | Swift extraction waterfall and index-store discovery |
+| Modify: `grapha-swift/src/treesitter.rs` | Current tree-sitter extractor plus all Swift enrichment passes |
+| Modify: `grapha/src/store/sqlite.rs` | Current SQLite schema, save/load, incremental sync, compatibility decode |
+| Create: `grapha-swift/src/treesitter/` | New focused Swift tree-sitter extraction/enrichment modules |
+| Create: `grapha/src/app/` or `grapha/src/commands/` | Extracted CLI orchestration and command handlers |
+| Create: `grapha/src/store/sqlite/` | Extracted SQLite schema/read/write helpers |
+| Modify: `grapha/tests/integration.rs` | CLI behavior regression coverage |
+| Modify: `grapha-swift/tests/*.rs` | Swift extraction/config regression coverage |
+
+---
+
+### Task 1: Fix the dead Swift index-store toggle
+
+**Files:**
+- Modify: `grapha/src/main.rs`
+- Modify: `grapha/src/config.rs`
+- Modify: `grapha-swift/src/lib.rs`
+- Modify: `grapha-core` extraction context files if pipeline options must be carried through shared context types
+- Test: existing Swift extraction tests or new targeted regression coverage in `grapha-swift/tests/`
+
+- [ ] Add a failing regression test that proves `[swift].index_store = false` prevents index-store extraction and falls back to SwiftSyntax/tree-sitter behavior.
+- [ ] Remove the `unsafe { std::env::set_var("GRAPHA_SKIP_INDEX_STORE", "1") }` branch from [main.rs](/Users/wendell/Developer/oops-rs/grapha/grapha/src/main.rs#L484) and replace it with explicit pipeline configuration.
+- [ ] Thread an `index_store_enabled` flag through the pipeline into `grapha_swift::extract_swift(...)` so the behavior is controlled by typed inputs rather than process-global state.
+- [ ] Update `grapha-swift/src/lib.rs` so `extract_swift` only initializes/uses index store when the flag is enabled.
+- [ ] Run targeted Swift tests, then `cargo test -p grapha-swift` and `cargo test -p grapha -- integration`.
+- [ ] Commit the fix separately before any structural refactor work.
+
+### Task 2: Split Swift tree-sitter extraction from enrichment passes
+
+**Files:**
+- Modify: `grapha-swift/src/treesitter.rs`
+- Create: `grapha-swift/src/treesitter/mod.rs`
+- Create: `grapha-swift/src/treesitter/extract.rs`
+- Create: `grapha-swift/src/treesitter/doc_comments.rs`
+- Create: `grapha-swift/src/treesitter/swiftui.rs`
+- Create: `grapha-swift/src/treesitter/localization.rs`
+- Create: `grapha-swift/src/treesitter/assets.rs`
+- Create: `grapha-swift/src/treesitter/common.rs` if shared span/index helpers remain cross-cutting
+- Test: existing Swift tree-sitter tests plus new module-focused unit tests
+
+- [ ] Freeze behavior first with targeted tests around doc-comment enrichment, SwiftUI structure enrichment, localization metadata, and asset reference tagging.
+- [ ] Keep a thin public facade at `grapha-swift/src/treesitter.rs` or `mod.rs` that re-exports the current public API so call sites stay stable during the split.
+- [ ] Move generic parser/shared types (`parse_swift`, `EnrichmentContext`, span helpers, dedup helpers) into `common`/`extract` modules.
+- [ ] Move each enrichment concern into its own file with the smallest possible public surface.
+- [ ] Eliminate duplicated low-level helpers such as line/byte indexing by consolidating them in one shared helper module.
+- [ ] Run `cargo test -p grapha-swift` after each extraction to keep the split behaviorally neutral.
+- [ ] Commit the module split once tests pass without changing CLI output.
+
+### Task 3: Extract CLI orchestration out of `main.rs`
+
+**Files:**
+- Modify: `grapha/src/main.rs`
+- Create: `grapha/src/app/mod.rs` or `grapha/src/commands/mod.rs`
+- Create: `grapha/src/app/pipeline.rs`
+- Create: `grapha/src/app/index.rs`
+- Create: `grapha/src/app/query.rs`
+- Create: `grapha/src/app/serve.rs`
+- Create: `grapha/src/cli.rs` if clap types are split from runtime behavior
+- Test: `grapha/tests/integration.rs`
+
+- [ ] Preserve the existing command-line contract with a smoke test matrix for `analyze`, `index`, `symbol`, `flow`, `l10n`, `asset`, `repo`, and `serve --mcp`.
+- [ ] Move `run_pipeline` and indexing orchestration out of `main.rs` into a dedicated runtime module.
+- [ ] Move command-specific handlers (`handle_symbol_command`, `handle_flow_command`, `handle_l10n_command`, `handle_asset_command`, `handle_repo_command`) into one or more command modules grouped by behavior rather than by output format.
+- [ ] Reduce `main()` to parsing CLI args, building render options, and dispatching into extracted runtime functions.
+- [ ] Keep watch-mode logic out of the CLI parsing layer by isolating it behind a `serve`/`watch` runtime module.
+- [ ] Run `cargo test -p grapha -- integration` and a manual `cargo run -p grapha -- --help` sanity check.
+- [ ] Commit this as a pure structure change with no query semantics changes.
+
+### Task 4: Split SQLite persistence into schema, write, and read paths
+
+**Files:**
+- Modify: `grapha/src/store/sqlite.rs`
+- Create: `grapha/src/store/sqlite/mod.rs`
+- Create: `grapha/src/store/sqlite/schema.rs`
+- Create: `grapha/src/store/sqlite/write.rs`
+- Create: `grapha/src/store/sqlite/read.rs`
+- Create: `grapha/src/store/sqlite/compat.rs`
+- Test: move or keep existing `#[cfg(test)]` coverage adjacent to new modules
+
+- [ ] Lock in behavior with focused tests for full save/load, incremental sync, `load_filtered`, and legacy schema compatibility.
+- [ ] Extract schema/version constants and table creation helpers into `schema.rs`.
+- [ ] Extract full/incremental write paths into `write.rs`, keeping `SqliteStore` as the stable facade type.
+- [ ] Extract all load/decode logic into `read.rs` and isolate schema-version-specific edge decoding into `compat.rs`.
+- [ ] Replace string-built filtering where possible with parameterized SQL or tightly-scoped helper builders so SQL assembly is explicit and testable.
+- [ ] Keep `load_filtered` semantics stable for the localization fast path used in [main.rs:825](/Users/wendell/Developer/oops-rs/grapha/grapha/src/main.rs#L825).
+- [ ] Run `cargo test -p grapha sqlite_store` and then full `cargo test`.
+- [ ] Commit after the persistence tests and integration tests both pass.
+
+### Task 5: Re-run smell analysis and tighten local thresholds
+
+**Files:**
+- Modify: `grapha/src/query/smells.rs` only if threshold tuning or exclusions are needed
+- Modify: relevant tests if smell output changes
+- Use: generated `.grapha/` index for local verification
+
+- [ ] Re-index the repo with `cargo run -p grapha -- index .`.
+- [ ] Run `cargo run -p grapha -- repo smells -p .` and compare the before/after warning set.
+- [ ] Confirm the original hotspots are reduced: dead config path removed, `treesitter.rs` split, `main.rs` slimmed down, `sqlite.rs` split.
+- [ ] Only adjust smell thresholds if the remaining warnings are demonstrably false positives after the refactors.
+- [ ] Capture the remaining warnings in the final PR description so future cleanup has an explicit baseline.
+
+### Task 6: Full verification and integration checkpoint
+
+**Files:**
+- No new code expected unless verification exposes regressions
+
+- [ ] Run `cargo fmt -- --check`.
+- [ ] Run `cargo clippy --all-targets --all-features`.
+- [ ] Run `cargo test`.
+- [ ] Run one real-world CLI smoke pass: `cargo run -p grapha -- index .` followed by `cargo run -p grapha -- repo smells -p .`.
+- [ ] If all checks pass, prepare either a cleanup PR or continue with any remaining smell-specific follow-up in a new plan rather than extending this refactor indefinitely.
+
+---
+
+## Notes
+
+- The highest-priority fix is Task 1 because it is a correctness issue, not just style.
+- Tasks 2 through 4 should be reviewed as structural refactors. Avoid mixing new feature behavior into those commits.
+- If the tree-sitter or SQLite splits reveal hidden coupling that would require semantic rewrites, stop and create a follow-up plan rather than forcing the decomposition in one pass.

grapha-core/src/pipeline.rs

@@ -69,6 +69,7 @@ pub fn file_context(context: &ProjectContext, modules: &ModuleMap, file: &Path)
         relative_path,
         absolute_path,
         module_name,
+        index_store_enabled: context.index_store_enabled,
     }
 }
 
@@ -208,6 +209,7 @@ mod tests {
         let project = ProjectContext {
             input_path: dir.path().to_path_buf(),
             project_root: dir.path().to_path_buf(),
+            index_store_enabled: true,
         };
         let mut modules = ModuleMap::new();
         modules.modules.insert("core".to_string(), vec![src_dir]);

grapha-core/src/plugin.rs

@@ -13,6 +13,7 @@ use crate::module::ModuleMap;
 pub struct ProjectContext {
     pub input_path: PathBuf,
     pub project_root: PathBuf,
+    pub index_store_enabled: bool,
 }
 
 impl ProjectContext {
@@ -21,6 +22,7 @@ impl ProjectContext {
             input_path: input_path.to_path_buf(),
             project_root: std::fs::canonicalize(input_path)
                 .unwrap_or_else(|_| input_path.to_path_buf()),
+            index_store_enabled: true,
         }
     }
 
@@ -36,6 +38,7 @@ pub struct FileContext {
     pub relative_path: PathBuf,
     pub absolute_path: PathBuf,
     pub module_name: Option<String>,
+    pub index_store_enabled: bool,
 }
 
 pub trait GraphPass: Send + Sync {

grapha-swift/src/lib.rs

@@ -47,7 +47,11 @@ impl LanguagePlugin for SwiftPlugin {
     }
 
     fn prepare_project(&self, context: &ProjectContext) -> anyhow::Result<()> {
-        prepare_project_index_store(&context.project_root);
+        if context.index_store_enabled {
+            prepare_project_index_store(&context.project_root);
+        } else {
+            clear_index_store_path(&context.project_root);
+        }
         Ok(())
     }
 
@@ -63,6 +67,7 @@ impl LanguagePlugin for SwiftPlugin {
             &context.relative_path,
             None,
             Some(&context.project_root),
+            context.index_store_enabled,
         )
     }
 
@@ -172,6 +177,17 @@ fn prepare_project_with<F>(
     let _ = refresh_index_store_with(cache, project_root, discover);
 }
 
+fn set_index_store_path_in(
+    cache: &RwLock<HashMap<PathBuf, Option<PathBuf>>>,
+    project_root: &Path,
+    store: Option<PathBuf>,
+) {
+    cache
+        .write()
+        .expect("index-store cache poisoned")
+        .insert(project_cache_key(project_root), store);
+}
+
 /// Force index-store rediscovery for a project, including after a cached miss.
 pub fn refresh_index_store(project_root: &Path) -> Option<PathBuf> {
     refresh_index_store_with(&INDEX_STORE_PATHS, project_root, discover_index_store)
@@ -228,6 +244,19 @@ pub fn index_store_path(project_root: &Path) -> Option<PathBuf> {
     index_store_path_in(&INDEX_STORE_PATHS, project_root)
 }
 
+/// Seed or clear the cached index-store path for a project.
+///
+/// This is primarily useful for tests and for explicit cache invalidation when
+/// a caller knows index-store should not be used for a project.
+pub fn set_index_store_path(project_root: &Path, store: Option<PathBuf>) {
+    set_index_store_path_in(&INDEX_STORE_PATHS, project_root, store);
+}
+
+/// Clear any cached index-store path for a project.
+pub fn clear_index_store_path(project_root: &Path) {
+    set_index_store_path(project_root, None);
+}
+
 fn index_store_path_in(
     cache: &RwLock<HashMap<PathBuf, Option<PathBuf>>>,
     project_root: &Path,
@@ -366,13 +395,40 @@ pub fn extract_swift(
     file_path: &Path,
     explicit_index_store_path: Option<&Path>,
     project_root: Option<&Path>,
+    index_store_enabled: bool,
 ) -> anyhow::Result<ExtractionResult> {
-    if let Some(root) = project_root {
-        init_index_store(root);
+    extract_swift_with_init(
+        source,
+        file_path,
+        explicit_index_store_path,
+        project_root,
+        index_store_enabled,
+        init_index_store,
+    )
+}
+
+fn extract_swift_with_init<F>(
+    source: &[u8],
+    file_path: &Path,
+    explicit_index_store_path: Option<&Path>,
+    project_root: Option<&Path>,
+    index_store_enabled: bool,
+    mut init_index_store_fn: F,
+) -> anyhow::Result<ExtractionResult>
+where
+    F: FnMut(&Path),
+{
+    if index_store_enabled && let Some(root) = project_root {
+        init_index_store_fn(root);
     }
-    let effective_store = explicit_index_store_path
-        .map(Path::to_path_buf)
-        .or_else(|| project_root.and_then(index_store_path));
+
+    let effective_store = if index_store_enabled {
+        explicit_index_store_path
+            .map(Path::to_path_buf)
+            .or_else(|| project_root.and_then(index_store_path))
+    } else {
+        None
+    };
 
     if let Some(store_path) = effective_store.as_deref() {
         // Index store needs absolute file path for matching
@@ -757,6 +813,40 @@ mod discovery_cache_tests {
     }
 }
 
+#[cfg(test)]
+mod index_store_toggle_tests {
+    use super::extract_swift_with_init;
+    use std::cell::Cell;
+    use std::path::Path;
+
+    #[test]
+    fn disabled_index_store_skips_initializer() {
+        let initializer_called = Cell::new(false);
+        let source = br#"
+        import SwiftUI
+
+        struct ContentView: View {
+            var body: some View {
+                Text("Hello")
+            }
+        }
+        "#;
+
+        let result = extract_swift_with_init(
+            source,
+            Path::new("ContentView.swift"),
+            None,
+            None,
+            false,
+            |_| initializer_called.set(true),
+        )
+        .unwrap();
+
+        assert!(!initializer_called.get());
+        assert!(result.nodes.iter().any(|node| node.name == "ContentView"));
+    }
+}
+
 #[cfg(test)]
 mod marker_tests {
     use super::{

grapha-swift/src/swiftsyntax.rs

@@ -165,7 +165,8 @@ mod tests {
         }
         "#;
 
-        let result = extract_swift(source, Path::new("ContentView.swift"), None, None).unwrap();
+        let result =
+            extract_swift(source, Path::new("ContentView.swift"), None, None, true).unwrap();
 
         let body = result
             .nodes