[gobby-#316] feat: release gcode 0.9.8 grouped output

Author: joshwilhelmi

CHANGELOG.md

@@ -9,6 +9,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.9.8] — gcode
+
+### Changed
+
+#### gcode
+
+- **Grouped text output** — `gcode grep` and high-volume navigation outputs now
+  reduce repeated file path prefixes by grouping text results under file or
+  directory headers, while JSON output remains unchanged.
+- **Quiet symbol retrieval** — `gcode outline`, `gcode symbol`, and
+  `gcode symbols` no longer print savings banners to stderr.
+
 ## [0.9.7] — gcode
 
 ### Fixed

Cargo.lock

@@ -1,6 +1,6 @@
 [package]
 name = "gobby-code"
-version = "0.9.7"
+version = "0.9.8"
 edition = "2024"
 rust-version = "1.88"
 authors = ["Josh Wilhelmi <hello@gobby.ai>"]

crates/gcode/Cargo.toml

@@ -167,6 +167,12 @@ gcode search --project /path/to/app "q"   # By path
 --no-freshness                            # Skip read-time index/source freshness checks
 ```
 
+`gcode grep` defaults to grouped text output: each matched file is printed once,
+followed by line-numbered matches and context. Other high-volume text outputs,
+including `tree`, `callers`, `usages`, and `blast-radius`, also group repeated
+paths for compact agent-readable output. JSON output keeps the stable structured
+shape.
+
 ## AI CLI Skill Installation
 
 For non-Gobby-managed projects, `gcode init` installs the bundled `gcode` skill

crates/gcode/README.md

@@ -13,7 +13,7 @@ This project is indexed. Use `gcode` via Bash for fast code search and navigatio
 
 ## Search
 
-- `gcode grep "pattern" [PATH ...] -m 50` — exact indexed content grep over `code_content_chunks`; defaults to text output for bounded line matches
+- `gcode grep "pattern" [PATH ...] -m 50` — exact indexed content grep over `code_content_chunks`; defaults to grouped text output for bounded line matches
 - `gcode search "query" [PATH ...]` — hybrid search: pg_search BM25 + semantic + graph boost (best for fuzzy or natural-language queries)
 - `gcode search-symbol "name" [PATH ...]` — exact-first symbol lookup with deterministic ranking; add `--with-graph` to include FalkorDB graph neighbors when available
 - `gcode search-text "query" [PATH ...]` — pg_search BM25 search on symbol names, signatures, and docstrings
@@ -43,7 +43,7 @@ Search output is intentionally snippet-sized. Broad file reads and wide line ran
 ## Navigation
 
 - `gcode repo-outline` — high-level project summary with module symbol counts
-- `gcode tree` — whole-project file tree with symbol counts per file; it takes no path argument
+- `gcode tree` — whole-project file tree with symbol counts per file; text output groups files by directory and it takes no path argument
 - `gcode kinds` — list distinct symbol kinds in the index (helps pick `--kind` values)
 
 For directory-focused exploration, use `gcode tree --format text` with shell filtering, or scope search commands with positional paths: `gcode search "query" crates/gcode/src docs/**/*.md`.
@@ -86,4 +86,4 @@ for the UI, but graph sync/read/lifecycle behavior lives in `gcode`.
 
 ## Output and global flags
 
-`gcode grep` defaults to text output; use `--format json` when you need structured matches and spans. Other commands support `--format text` for human-readable output where available. Use `--quiet` to suppress warnings, and `--no-freshness` to skip the read-time staleness check (cheaper when you know the index is current).
+`gcode grep` defaults to grouped text output; use `--format json` when you need structured matches and spans. High-volume text outputs such as `tree`, `callers`, `usages`, and `blast-radius` group repeated paths under directory or file headers. Other commands support `--format text` for human-readable output where available. Use `--quiet` to suppress warnings, and `--no-freshness` to skip the read-time staleness check (cheaper when you know the index is current).

crates/gcode/assets/SKILL.md

@@ -1,9 +1,12 @@
+use std::collections::BTreeMap;
+
 use crate::config::Context;
 use crate::db;
 use crate::graph::code_graph::{
     self, GraphBlastRadiusTarget, GraphLifecycleAction, GraphLifecycleOutput, GraphPayload,
 };
 use crate::graph::report::{ProjectGraphReport, ProjectGraphReportOptions};
+use crate::models::GraphResult;
 use crate::models::PagedResponse;
 use crate::output::{self, Format};
 use crate::projection::sync::ProjectionSyncReport;
@@ -451,6 +454,34 @@ fn empty_paged_response<T: Serialize>(
     }
 }
 
+fn format_grouped_graph_results<F>(results: &[GraphResult], format_line: F) -> String
+where
+    F: Fn(&GraphResult) -> String,
+{
+    let mut grouped: BTreeMap<&str, Vec<&GraphResult>> = BTreeMap::new();
+    for result in results {
+        grouped.entry(&result.file_path).or_default().push(result);
+    }
+
+    let mut lines = Vec::new();
+    for (file_path, mut entries) in grouped {
+        lines.push(if file_path.is_empty() {
+            "<unknown>".to_string()
+        } else {
+            file_path.to_string()
+        });
+        entries.sort_by(|a, b| {
+            a.line
+                .cmp(&b.line)
+                .then_with(|| a.name.cmp(&b.name))
+                .then_with(|| a.relation.cmp(&b.relation))
+                .then_with(|| a.distance.cmp(&b.distance))
+        });
+        lines.extend(entries.into_iter().map(&format_line));
+    }
+    lines.join("\n")
+}
+
 /// Resolve user input to a canonical symbol id, printing suggestions on ambiguity.
 /// Returns None and prints an error message if no match found.
 fn resolve_symbol(ctx: &Context, input: &str) -> Option<ResolvedGraphSymbol> {
@@ -539,12 +570,9 @@ pub fn callers(
             } else if results.is_empty() {
                 eprintln!("No callers at offset {offset} (total {total})");
             } else {
-                for r in &results {
-                    println!(
-                        "{}:{} {} -> {}",
-                        r.file_path, r.line, r.name, symbol.display_name
-                    );
-                }
+                output::print_text(&format_grouped_graph_results(&results, |r| {
+                    format!("{} {} -> {}", r.line, r.name, symbol.display_name)
+                }))?;
                 if total > offset + results.len() {
                     eprintln!(
                         "-- {} of {} results (use --offset {} for more)",
@@ -607,13 +635,10 @@ pub fn usages(
             } else if results.is_empty() {
                 eprintln!("No usages at offset {offset} (total {total})");
             } else {
-                for r in &results {
+                output::print_text(&format_grouped_graph_results(&results, |r| {
                     let rel = r.relation.as_deref().unwrap_or("unknown");
-                    println!(
-                        "{}:{} [{}] {} -> {}",
-                        r.file_path, r.line, rel, r.name, symbol.display_name
-                    );
-                }
+                    format!("{} [{}] {} -> {}", r.line, rel, r.name, symbol.display_name)
+                }))?;
                 if total > offset + results.len() {
                     eprintln!(
                         "-- {} of {} results (use --offset {} for more)",
@@ -703,10 +728,10 @@ pub fn blast_radius(
                 println!("No blast radius found for '{}'", symbol.display_name);
                 print_graph_hint_text(ctx);
             } else {
-                for r in &results {
+                output::print_text(&format_grouped_graph_results(&results, |r| {
                     let dist = r.distance.unwrap_or(0);
-                    println!("{}:{} [distance={}] {}", r.file_path, r.line, dist, r.name);
-                }
+                    format!("{} [distance={}] {}", r.line, dist, r.name)
+                }))?;
             }
             Ok(())
         }
@@ -738,7 +763,9 @@ mod tests {
     fn graph_reads_degrade_when_falkor_missing() {
         let ctx = make_ctx_no_falkordb();
 
-        imports(&ctx, "src/lib.rs", Format::Text).expect("imports degrade to empty output");
+        let result = imports(&ctx, "src/lib.rs", Format::Text);
+
+        assert!(result.is_ok(), "imports should degrade cleanly: {result:?}");
     }
 
     #[test]
@@ -759,6 +786,45 @@ mod tests {
         assert!(!text.trim_start().starts_with('#'));
     }
 
+    #[test]
+    fn graph_text_groups_by_file_and_sorts_entries() {
+        let results = vec![
+            GraphResult {
+                id: "b".to_string(),
+                name: "beta".to_string(),
+                file_path: "src/b.rs".to_string(),
+                line: 9,
+                relation: Some("CALLS".to_string()),
+                distance: None,
+                metadata: None,
+            },
+            GraphResult {
+                id: "a2".to_string(),
+                name: "zeta".to_string(),
+                file_path: "src/a.rs".to_string(),
+                line: 8,
+                relation: Some("CALLS".to_string()),
+                distance: None,
+                metadata: None,
+            },
+            GraphResult {
+                id: "a1".to_string(),
+                name: "alpha".to_string(),
+                file_path: "src/a.rs".to_string(),
+                line: 3,
+                relation: Some("CALLS".to_string()),
+                distance: None,
+                metadata: None,
+            },
+        ];
+
+        let text = format_grouped_graph_results(&results, |result| {
+            format!("{} {}", result.line, result.name)
+        });
+
+        assert_eq!(text, "src/a.rs\n3 alpha\n8 zeta\nsrc/b.rs\n9 beta");
+    }
+
     #[test]
     fn report_requires_graph_service() {
         let ctx = make_ctx_no_falkordb();

crates/gcode/src/commands/graph.rs

@@ -111,7 +111,6 @@ fn load_indexed_chunks(
 ) -> anyhow::Result<Vec<IndexedContentChunk>> {
     let rows = conn.query(
         "SELECT c.file_path,
-                c.chunk_index::BIGINT AS chunk_index,
                 c.line_start::BIGINT AS line_start,
                 c.content
          FROM code_content_chunks c
@@ -328,29 +327,66 @@ fn format_text_matches(matches: &[GrepMatch]) -> String {
     let matching_lines: BTreeSet<(String, usize)> =
         matches.iter().map(|m| (m.path.clone(), m.line)).collect();
     let mut emitted_context = BTreeSet::new();
+    let mut current_path: Option<&str> = None;
     let mut lines = Vec::new();
 
     for item in matches {
         for context in &item.before {
             let key = (item.path.clone(), context.line);
             if !matching_lines.contains(&key) && emitted_context.insert(key) {
-                lines.push(format!("{}-{}-{}", item.path, context.line, context.text));
+                push_grouped_grep_line(
+                    &mut lines,
+                    &mut current_path,
+                    &item.path,
+                    context.line,
+                    '-',
+                    &context.text,
+                );
             }
         }
 
-        lines.push(format!("{}:{}:{}", item.path, item.line, item.text));
+        push_grouped_grep_line(
+            &mut lines,
+            &mut current_path,
+            &item.path,
+            item.line,
+            ':',
+            &item.text,
+        );
 
         for context in &item.after {
             let key = (item.path.clone(), context.line);
             if !matching_lines.contains(&key) && emitted_context.insert(key) {
-                lines.push(format!("{}-{}-{}", item.path, context.line, context.text));
+                push_grouped_grep_line(
+                    &mut lines,
+                    &mut current_path,
+                    &item.path,
+                    context.line,
+                    '-',
+                    &context.text,
+                );
             }
         }
     }
 
     lines.join("\n")
 }
 
+fn push_grouped_grep_line<'a>(
+    lines: &mut Vec<String>,
+    current_path: &mut Option<&'a str>,
+    path: &'a str,
+    line: usize,
+    marker: char,
+    text: &str,
+) {
+    if *current_path != Some(path) {
+        lines.push(path.to_string());
+        *current_path = Some(path);
+    }
+    lines.push(format!("{line}{marker}{text}"));
+}
+
 fn i64_to_usize(value: i64, column: &str) -> anyhow::Result<usize> {
     value
         .try_into()
@@ -385,11 +421,25 @@ mod tests {
     }
 
     #[test]
-    fn text_renders_grep_shape() {
+    fn text_renders_grouped_grep_shape() {
         let chunks = vec![chunk("src/lib.rs", 1, "one\nneedle\nthree")];
         let result = grep_chunks(&chunks, &options("needle")).expect("grep chunks");
 
-        assert_eq!(format_text_matches(&result.matches), "src/lib.rs:2:needle");
+        assert_eq!(format_text_matches(&result.matches), "src/lib.rs\n2:needle");
+    }
+
+    #[test]
+    fn text_groups_multiple_files() {
+        let chunks = vec![
+            chunk("src/a.rs", 1, "needle a"),
+            chunk("tests/b.rs", 10, "needle b"),
+        ];
+        let result = grep_chunks(&chunks, &options("needle")).expect("grep chunks");
+
+        assert_eq!(
+            format_text_matches(&result.matches),
+            "src/a.rs\n1:needle a\ntests/b.rs\n10:needle b"
+        );
     }
 
     #[test]
@@ -461,7 +511,24 @@ mod tests {
         );
         assert_eq!(
             format_text_matches(&result.matches),
-            "src/lib.rs-2-two\nsrc/lib.rs:3:needle\nsrc/lib.rs-4-four\nsrc/lib.rs-5-five"
+            "src/lib.rs\n2-two\n3:needle\n4-four\n5-five"
+        );
+    }
+
+    #[test]
+    fn text_suppresses_duplicate_context_lines() {
+        let chunks = vec![chunk(
+            "src/lib.rs",
+            1,
+            "one\nneedle one\nmiddle\nneedle two\nfive",
+        )];
+        let mut opts = options("needle");
+        opts.context = Some(1);
+        let result = grep_chunks(&chunks, &opts).expect("grep chunks");
+
+        assert_eq!(
+            format_text_matches(&result.matches),
+            "src/lib.rs\n1-one\n2:needle one\n3-middle\n4:needle two\n5-five"
         );
     }
 
@@ -482,6 +549,10 @@ mod tests {
         assert_eq!(result.matches[0].line, 2);
         assert_eq!(result.matches[0].before.len(), 1);
         assert_eq!(result.matches[0].after.len(), 1);
+        assert_eq!(
+            format_text_matches(&result.matches),
+            "src/lib.rs\n1-before\n2:needle one\n3-middle"
+        );
     }
 
     #[test]