fix(review): close all 2026-06-03 codebase-review findings (R1-R18)

Resolves the 18 findings from the parallel codebase review, tracked in
development/vimwiki-gap.md.

Correctness / perf:
- Wiki.config -> Arc<WikiConfig> so cloning a Wiki is a refcount bump (R5)
- WorkspaceIndex::remove is no longer O(n^2): a per-source contributions
  map limits the scan to buckets the source actually wrote into (R6)
- render_color now expands color_tag_template (__STYLE__/__CONTENT__),
  consuming the previously-dead field; ColorNode documented as an
  extension point; 3 renderer tests added (R3/R4)
- wiki_root_for returns empty/nil on no-match instead of falling back to
  the first wiki (R2); auto_header honours links_space_char (R7)

Cleanup / dedup:
- Remove dead #[allow(dead_code)] stubs + uncalled pub helpers, narrow
  imports (R10/R11)
- Dedup span_of_inline x3 -> InlineNode::span() (R12)
- diary_step single read lock; page_captions single pass (R13)
- Lua auto_header loop -> wiki_list(); detect_current_symbol cleanup
  (R14/R18)

Client / docs:
- :VimwikiNormalizeLink Vim cmds -> <q-args> (R17); ftplugin header fix
  (R16); vars.vim multi-wiki limitation documented (R15)
- Document 19 config options in README.md + doc/nuwiki.txt; fix
  list_margin/shiftwidth doc and stale comments (R1/R9)
- R8 investigated, confirmed not a real bug (documented)

Verified: Neovim harness 307, Vim harness 301/18/21, Rust suite 568, all
0 failed; clippy clean; fresh parallel-agent audit found no regressions.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

crates/nuwiki-lsp/src/commands.rs

@@ -499,24 +499,19 @@ fn diary_step(backend: &Backend, args: Vec<Value>, forward: bool) -> Result<Opti
     let Some(wiki) = backend.wiki_for_uri(&p.uri) else {
         return Ok(None);
     };
-    // Pivot period: prefer the current page's own period (any flavour),
-    // falling back to the wiki's configured frequency for "today" when
-    // the cursor isn't on a diary page. This makes <C-Down> on a weekly
-    // entry jump to the next weekly entry, not the next daily one.
-    let pivot: nuwiki_core::date::DiaryPeriod = {
-        let idx = wiki
-            .index
-            .read()
-            .map_err(|_| "index lock poisoned".to_string())?;
-        idx.page(&p.uri)
-            .and_then(|page| page.diary_period)
-            .unwrap_or_else(|| wiki.config.diary_calendar().today())
-    };
     let next = {
         let idx = wiki
             .index
             .read()
             .map_err(|_| "index lock poisoned".to_string())?;
+        // Pivot period: prefer the current page's own period (any flavour),
+        // falling back to the wiki's configured frequency for "today" when
+        // the cursor isn't on a diary page. This makes <C-Down> on a weekly
+        // entry jump to the next weekly entry, not the next daily one.
+        let pivot: nuwiki_core::date::DiaryPeriod = idx
+            .page(&p.uri)
+            .and_then(|page| page.diary_period)
+            .unwrap_or_else(|| wiki.config.diary_calendar().today());
         if forward {
             crate::diary::next_period(&idx, &pivot)
         } else {
@@ -1911,10 +1906,12 @@ pub mod ops {
     pub fn page_captions(
         index: &crate::index::WorkspaceIndex,
     ) -> std::collections::BTreeMap<String, String> {
+        // Single pass over the page table — no per-name name→uri→page double
+        // lookup. The BTreeMap keeps the output name-sorted.
         let mut map = std::collections::BTreeMap::new();
-        for name in index.page_names() {
-            if let Some(h) = index.page_by_name(&name).and_then(|p| p.headings.first()) {
-                map.insert(name, h.title.clone());
+        for page in index.pages_by_uri.values() {
+            if let Some(h) = page.headings.first() {
+                map.insert(page.name.clone(), h.title.clone());
             }
         }
         map
@@ -3267,7 +3264,6 @@ pub mod ops {
     // `tag_links_edit` powers `nuwiki.tags.generateLinks`; the rebuild
     // command is a direct re-walk of the wiki root in the dispatcher.
 
-    use crate::index::TagOccurrence;
     use nuwiki_core::ast::TagScope;
 
     /// One row returned by `nuwiki.tags.search`. Serialised as
@@ -3460,11 +3456,6 @@ pub mod ops {
         )
     }
 
-    // Keep the import live for downstream use even when the local module
-    // doesn't reference it directly.
-    #[allow(dead_code)]
-    fn _retain_tag_occurrence_import(_o: &TagOccurrence) {}
-
     fn whole_doc_span(text: &str) -> Span {
         let bytes = text.as_bytes();
         let mut line = 0u32;
@@ -3495,7 +3486,7 @@ pub mod ops {
 /// Kept out of `ops` because everything here is side-effecting — pure
 /// rendering / templating lives in [`crate::export`].
 pub mod export_ops {
-    use std::path::{Path, PathBuf};
+    use std::path::PathBuf;
 
     use nuwiki_core::ast::DocumentNode;
     use nuwiki_core::date::DiaryDate;
@@ -3876,9 +3867,4 @@ pub mod export_ops {
         }
         out
     }
-
-    /// Re-export so the dispatcher doesn't have to know about the export
-    /// module's path manipulation primitives.
-    #[allow(dead_code)]
-    pub fn _silence_unused(_: &Path) {}
 }

crates/nuwiki-lsp/src/config.rs

@@ -12,7 +12,7 @@
 use std::path::{Path, PathBuf};
 
 use serde::Deserialize;
-use tower_lsp::lsp_types::{InitializeParams, Url};
+use tower_lsp::lsp_types::InitializeParams;
 
 #[derive(Debug, Clone, Default)]
 pub struct Config {
@@ -198,9 +198,11 @@ pub struct HtmlConfig {
     /// vimwiki `user_htmls`: basenames of HTML files with no wiki source that
     /// `allToHtml` must not prune. Empty by default.
     pub user_htmls: Vec<String>,
-    /// vimwiki `color_tag_template`: HTML template for a colour span. The
-    /// `__COLORFG__` / `__COLORBG__` / `__CONTENT__` placeholders are filled
-    /// from `color_dic`. Default matches upstream's `<span style=…>` template.
+    /// vimwiki `color_tag_template`: HTML template for a colour span whose name
+    /// resolves in `color_dic`. `__STYLE__` expands to the inline style
+    /// (`color:<css>`) and `__CONTENT__` to the rendered inner HTML. Default
+    /// matches upstream's `<span style="…">…</span>` template. Consumed by
+    /// `HtmlRenderer::render_color`.
     pub color_tag_template: String,
 }
 
@@ -1070,6 +1072,3 @@ pub fn config_from_json(value: serde_json::Value) -> Config {
     cfg.apply_change(&value);
     cfg
 }
-
-#[allow(dead_code)]
-fn _ensure_url_is_used(_u: &Url) {}

crates/nuwiki-lsp/src/edits.rs

@@ -88,14 +88,6 @@ impl WorkspaceEditBuilder {
         self
     }
 
-    pub fn edits<I>(&mut self, uri: Url, edits: I) -> &mut Self
-    where
-        I: IntoIterator<Item = TextEdit>,
-    {
-        self.changes.entry(uri).or_default().extend(edits);
-        self
-    }
-
     pub fn file_op(&mut self, op: DocumentChangeOperation) -> &mut Self {
         self.ops.push(op);
         self

crates/nuwiki-lsp/src/export.rs

@@ -16,13 +16,13 @@
 //!   above wired up; returns the final HTML string.
 
 use std::collections::HashMap;
-use std::path::{Path, PathBuf};
+use std::path::PathBuf;
 
 use nuwiki_core::ast::{BlockNode, DocumentNode, HeadingNode, InlineNode, LinkKind};
 use nuwiki_core::date::DiaryDate;
 use nuwiki_core::render::{HtmlRenderer, Renderer};
 
-use crate::config::{HtmlConfig, WikiConfig};
+use crate::config::HtmlConfig;
 
 /// Map a page name (e.g. `"diary/2026-05-11"`) to its on-disk HTML
 /// output path under `html_path`. Honours
@@ -251,6 +251,9 @@ pub fn render_page_html(
     if !cfg.color_dic.is_empty() {
         r = r.with_colors(cfg.color_dic.clone());
     }
+    if !cfg.color_tag_template.is_empty() {
+        r = r.with_color_template(cfg.color_tag_template.clone());
+    }
     if cfg.html_header_numbering > 0 {
         r = r.with_header_numbering(
             cfg.html_header_numbering,
@@ -425,9 +428,3 @@ code{background:#f4f4f4;padding:.1em .25em;border-radius:3px}\
 table{border-collapse:collapse}\
 table td,table th{border:1px solid #ccc;padding:.25em .5em}\
 ul.toc{padding-left:1.5em}\n";
-
-/// Convenience wrapper exposed for the dispatcher: convert a wiki config
-/// to the absolute output dir.
-pub fn html_output_dir(cfg: &WikiConfig) -> &Path {
-    &cfg.html.html_path
-}

crates/nuwiki-lsp/src/index.rs

@@ -123,6 +123,18 @@ pub struct WorkspaceIndex {
     /// the nav handlers (tag-as-anchor `definition`, `workspace/symbol`
     /// inclusion) and the `nuwiki.tags.search` command.
     pub tags_by_name: HashMap<String, Vec<TagOccurrence>>,
+    /// For each source URI, the backlink-bucket keys and tag-bucket names it
+    /// contributed. Lets `remove` touch only the affected buckets instead of
+    /// scanning every bucket in the workspace (O(touched), not O(total)).
+    contributions: HashMap<Url, SourceContributions>,
+}
+
+/// The bucket keys a single source page wrote into, so they can be undone
+/// in `remove` without a full scan. See [`WorkspaceIndex::contributions`].
+#[derive(Debug, Default)]
+struct SourceContributions {
+    backlink_keys: Vec<String>,
+    tag_names: Vec<String>,
 }
 
 impl WorkspaceIndex {
@@ -175,15 +187,20 @@ impl WorkspaceIndex {
         };
         index_blocks(&ast.children, &mut page);
 
+        let mut contrib = SourceContributions::default();
         let ext = self.file_extension.as_deref();
         for link in &page.outgoing {
             if let Some(tgt) = &link.target_page {
                 let key = canonical_link_name(tgt, &name, link.is_absolute, ext);
-                self.backlinks.entry(key).or_default().push(Backlink {
-                    source_uri: uri.clone(),
-                    source_span: link.span,
-                    target_anchor: link.anchor.clone(),
-                });
+                self.backlinks
+                    .entry(key.clone())
+                    .or_default()
+                    .push(Backlink {
+                        source_uri: uri.clone(),
+                        source_span: link.span,
+                        target_anchor: link.anchor.clone(),
+                    });
+                contrib.backlink_keys.push(key);
             }
         }
 
@@ -197,7 +214,9 @@ impl WorkspaceIndex {
                     span: tag.span,
                     scope: tag.scope,
                 });
+            contrib.tag_names.push(tag.name.clone());
         }
+        self.contributions.insert(uri.clone(), contrib);
 
         self.pages_by_name.insert(name, uri.clone());
         self.pages_by_uri.insert(uri, page);
@@ -207,14 +226,26 @@ impl WorkspaceIndex {
         if let Some(page) = self.pages_by_uri.remove(uri) {
             self.pages_by_name.remove(&page.name);
         }
-        for entries in self.backlinks.values_mut() {
-            entries.retain(|b| &b.source_uri != uri);
+        // Only revisit the buckets this source actually wrote into, instead
+        // of scanning every backlink/tag bucket in the workspace.
+        if let Some(contrib) = self.contributions.remove(uri) {
+            for key in contrib.backlink_keys {
+                if let Some(entries) = self.backlinks.get_mut(&key) {
+                    entries.retain(|b| &b.source_uri != uri);
+                    if entries.is_empty() {
+                        self.backlinks.remove(&key);
+                    }
+                }
+            }
+            for name in contrib.tag_names {
+                if let Some(entries) = self.tags_by_name.get_mut(&name) {
+                    entries.retain(|t| &t.uri != uri);
+                    if entries.is_empty() {
+                        self.tags_by_name.remove(&name);
+                    }
+                }
+            }
         }
-        self.backlinks.retain(|_, v| !v.is_empty());
-        for entries in self.tags_by_name.values_mut() {
-            entries.retain(|t| &t.uri != uri);
-        }
-        self.tags_by_name.retain(|_, v| !v.is_empty());
     }
 
     /// All occurrences of a tag across the workspace. Empty slice when the
@@ -306,21 +337,6 @@ impl WorkspaceIndex {
     }
 }
 
-/// Return a parsed [`DiaryDate`] when `uri` is a daily diary entry —
-/// the path lives under `<root>/<diary_rel_path>/` and its stem parses
-/// as `YYYY-MM-DD`. For weekly/monthly/yearly entries see
-/// [`diary_period_for_uri`].
-pub fn diary_date_for_uri(
-    uri: &Url,
-    root: Option<&Path>,
-    diary_rel_path: Option<&str>,
-) -> Option<DiaryDate> {
-    match diary_period_for_uri(uri, root, diary_rel_path)? {
-        nuwiki_core::date::DiaryPeriod::Day(d) => Some(d),
-        _ => None,
-    }
-}
-
 /// Return a parsed [`DiaryPeriod`] when `uri` is a diary entry at any of
 /// the four supported frequencies. Recognises:
 ///
@@ -329,9 +345,8 @@ pub fn diary_date_for_uri(
 ///   `YYYY-MM`       → Month
 ///   `YYYY`          → Year
 ///
-/// As with `diary_date_for_uri`, the path must sit under
-/// `<root>/<diary_rel_path>/` to be accepted; without a `root` we accept
-/// any stem (so ad-hoc test setups still work).
+/// The path must sit under `<root>/<diary_rel_path>/` to be accepted;
+/// without a `root` we accept any stem (so ad-hoc test setups still work).
 pub fn diary_period_for_uri(
     uri: &Url,
     root: Option<&Path>,

crates/nuwiki-lsp/src/lib.rs

@@ -110,9 +110,8 @@ pub async fn run_stdio() -> io::Result<()> {
 struct DocumentState {
     text: String,
     ast: DocumentNode,
-    /// Last version we observed from the client. Held even
-    /// though nothing reads it back yet.
-    #[allow(dead_code)]
+    /// Last version we observed from the client. Echoed back on the
+    /// diagnostics we publish for this document.
     version: i32,
 }
 

crates/nuwiki-lsp/src/nav.rs

@@ -94,7 +94,7 @@ fn find_in_list_item(item: &ListItemNode, line: u32, col: u32) -> Option<&Inline
 
 fn find_in_inlines(inlines: &[InlineNode], line: u32, col: u32) -> Option<&InlineNode> {
     for n in inlines {
-        if !span_contains(span_of_inline(n), line, col) {
+        if !span_contains(n.span(), line, col) {
             continue;
         }
         // Descend into inline containers so we return the *innermost* hit.
@@ -127,24 +127,3 @@ fn span_contains(s: Span, line: u32, col: u32) -> bool {
     let p = (line, col);
     p >= start && p < end
 }
-
-pub fn span_of_inline(node: &InlineNode) -> Span {
-    match node {
-        InlineNode::Text(n) => n.span,
-        InlineNode::Bold(n) => n.span,
-        InlineNode::Italic(n) => n.span,
-        InlineNode::BoldItalic(n) => n.span,
-        InlineNode::Strikethrough(n) => n.span,
-        InlineNode::Code(n) => n.span,
-        InlineNode::Superscript(n) => n.span,
-        InlineNode::Subscript(n) => n.span,
-        InlineNode::MathInline(n) => n.span,
-        InlineNode::Keyword(n) => n.span,
-        InlineNode::Color(n) => n.span,
-        InlineNode::WikiLink(n) => n.span,
-        InlineNode::ExternalLink(n) => n.span,
-        InlineNode::Transclusion(n) => n.span,
-        InlineNode::RawUrl(n) => n.span,
-        InlineNode::SoftBreak(n) => n.span,
-    }
-}

crates/nuwiki-lsp/src/semantic_tokens.rs

@@ -181,7 +181,7 @@ fn emit_block(block: &BlockNode, text: &str, idx: &LineIndex, out: &mut Vec<RawT
             for item in &dl.items {
                 if let Some(term) = &item.term {
                     if let (Some(first), Some(last)) = (term.first(), term.last()) {
-                        let s = Span::new(span_of_inline(first).start, span_of_inline(last).end);
+                        let s = Span::new(first.span().start, last.span().end);
                         split_span(s, text, idx, TOKEN_DEFINITION_TERM, 0, out);
                     }
                 }
@@ -251,27 +251,6 @@ fn emit_inlines(inlines: &[InlineNode], text: &str, idx: &LineIndex, out: &mut V
     }
 }
 
-fn span_of_inline(node: &InlineNode) -> Span {
-    match node {
-        InlineNode::Text(n) => n.span,
-        InlineNode::Bold(n) => n.span,
-        InlineNode::Italic(n) => n.span,
-        InlineNode::BoldItalic(n) => n.span,
-        InlineNode::Strikethrough(n) => n.span,
-        InlineNode::Code(n) => n.span,
-        InlineNode::Superscript(n) => n.span,
-        InlineNode::Subscript(n) => n.span,
-        InlineNode::MathInline(n) => n.span,
-        InlineNode::Keyword(n) => n.span,
-        InlineNode::Color(n) => n.span,
-        InlineNode::WikiLink(n) => n.span,
-        InlineNode::ExternalLink(n) => n.span,
-        InlineNode::Transclusion(n) => n.span,
-        InlineNode::RawUrl(n) => n.span,
-        InlineNode::SoftBreak(n) => n.span,
-    }
-}
-
 /// Convert a `Span` (potentially multi-line) into one or more single-line
 /// `RawToken`s. The LSP wire format can't express tokens that span newlines,
 /// so we split on line boundaries.

crates/nuwiki-lsp/src/wiki.rs

@@ -19,7 +19,10 @@ pub struct WikiId(pub u32);
 #[derive(Clone)]
 pub struct Wiki {
     pub id: WikiId,
-    pub config: WikiConfig,
+    // `Arc` so cloning a `Wiki` (done on every handler entry that picks a
+    // wiki out of the list) is a refcount bump, not a deep copy of the whole
+    // config — color_dic, templates, header strings, and so on.
+    pub config: Arc<WikiConfig>,
     pub index: Arc<RwLock<WorkspaceIndex>>,
 }
 
@@ -29,7 +32,11 @@ impl Wiki {
             .with_diary_rel_path(Some(config.diary_rel_path.clone()))
             .with_file_extension(Some(config.file_extension.clone()));
         let index = Arc::new(RwLock::new(index));
-        Self { id, config, index }
+        Self {
+            id,
+            config: Arc::new(config),
+            index,
+        }
     }
 
     /// True when `uri` resolves to a file under this wiki's root.