Follow the family into buffers and annotations

Files and searches already work across related projects; buffers and
TODOs are the other two things you want when a library and its caller are
separate repositories.  s-p n b switches to a buffer open in any of them,
s-p n o runs multi-occur over those buffers, and s-p n t gathers the
family's annotations into the search reviewer.

`projectile-project-buffers' already took a project, so the group form is
a mapcan over it, de-duplicated because two members can nest.  Todos
needed a little more: its body now takes a list of projects, and
`projectile-todos' is the single-project call of it, the way
`projectile-search-review' is for search.

Author: bbatsov

CHANGELOG.md

@@ -11,6 +11,8 @@
 - [#2160](https://github.com/bbatsov/projectile/pull/2160): Add `projectile-find-file-in-sibling-projects` (`s-p n f`) and `projectile-search-in-sibling-projects` (`s-p n s`), which work across the family of related projects rather than just the one you're in.
   - Both are built on `projectile-find-file-in-projects` and `projectile-search-in-projects`, which take any list of projects, so a command for a group of your own is a two-line wrapper.
   - A group search puts every match in one `*projectile-search*` buffer, named relative to the directory containing the group, so each one is labelled with the project it came from.
+- [#2163](https://github.com/bbatsov/projectile/pull/2163): Add `projectile-switch-to-buffer-in-sibling-projects` (`s-p n b`), `projectile-multi-occur-in-sibling-projects` (`s-p n o`) and `projectile-todos-in-sibling-projects` (`s-p n t`), so buffers and annotations follow the same family as files and searches.
+  - `projectile-switch-to-buffer-in-projects` joins the two existing generic commands, and `projectile-todos` now shares one implementation with its group form.
 
 ### Changes
 

doc/modules/ROOT/pages/across_repositories.adoc

@@ -26,8 +26,16 @@ directories is the right one.
 | kbd:[s-p n p] | `projectile-switch-sibling-project`
 | kbd:[s-p n f] | `projectile-find-file-in-sibling-projects`
 | kbd:[s-p n s] | `projectile-search-in-sibling-projects`
+| kbd:[s-p n b] | `projectile-switch-to-buffer-in-sibling-projects`
+| kbd:[s-p n o] | `projectile-multi-occur-in-sibling-projects`
+| kbd:[s-p n t] | `projectile-todos-in-sibling-projects`
 |===
 
+kbd:[s-p n] is the prefix for everything that works across related
+projects, and each key under it is the project-wide one a level down -
+kbd:[s-p f] finds a file here, kbd:[s-p n f] finds one anywhere in the
+family.
+
 The two switch commands honour `projectile-switch-project-action`, and both
 take a prefix argument to run `projectile-dispatch` instead, exactly like the
 other switch commands.
@@ -221,6 +229,16 @@ commands work on the whole group at once, the current project included:
 * kbd:[s-p n s] (`projectile-search-in-sibling-projects`) searches them all
   and collects the matches in one `*projectile-search*` buffer. A prefix
   argument makes the term an Emacs regexp.
+* kbd:[s-p n t] (`projectile-todos-in-sibling-projects`) gathers the
+  family's `TODO`/`FIXME` annotations into that same buffer.
+* kbd:[s-p n b] (`projectile-switch-to-buffer-in-sibling-projects`)
+  completes over the buffers you have open in any of them, so you can
+  jump between a library and its caller without caring which project a
+  buffer belongs to.
+* kbd:[s-p n o] (`projectile-multi-occur-in-sibling-projects`) runs
+  `multi-occur` over those same buffers. Note this searches what you have
+  open, not the projects on disk - kbd:[s-p n s] is the one that reads
+  files.
 
 The search results are named relative to the innermost directory holding
 the group, so each match says which project it came from:
@@ -238,8 +256,10 @@ re-search, exporting to `grep-mode`, and kbd:[r] to turn it into a
 reviewable replacement across all of them. See
 xref:usage.adoc[the search and replace reviewers].
 
-Both commands take a plain list of projects underneath, so a command for
-a group of your own is a two-line wrapper:
+These all take a plain list of projects underneath -
+`projectile-find-file-in-projects`, `projectile-search-in-projects` and
+`projectile-switch-to-buffer-in-projects` - so a command for a group of
+your own is a two-line wrapper:
 
 [source,elisp]
 ----
@@ -250,7 +270,9 @@ a group of your own is a two-line wrapper:
    "Find file in infra: "))
 ----
 
-`projectile-search-in-projects` is the same shape for searching.
+`projectile-search-in-projects` and
+`projectile-switch-to-buffer-in-projects` are the same shape for
+searching and for buffers.
 
 NOTE: A group search skips the ripgrep fast-path, which runs one `rg` over
 one directory tree, so it's slower than searching a single project. Each

doc/modules/ROOT/pages/cheatsheet.adoc

@@ -88,6 +88,15 @@ Here's a list of the interactive Emacs Lisp functions, provided by Projectile:
 | kbd:[s-p n s]
 | Search the current project and the ones related to it, collecting every match in one reviewable buffer. With a prefix argument the term is an Emacs regexp (see xref:across_repositories.adoc[Working across repositories]).
 
+| kbd:[s-p n t]
+| Collect the `TODO`/`FIXME`-style annotations of the current project and the ones related to it into the reviewable search buffer.
+
+| kbd:[s-p n b]
+| Switch to a buffer open in the current project or in any related to it.
+
+| kbd:[s-p n o]
+| Do a `multi-occur` in the buffers open in the current project and the ones related to it. With a prefix argument, show that many lines of context.
+
 | kbd:[s-p v]
 | Run `vc-dir` on the root directory of the project.
 

projectile.el

@@ -11296,7 +11296,15 @@ in the results buffer.  The keyword does not have to sit in a comment.
 With a prefix argument ARG, prompt for which keywords to search for
 instead of using all of them."
   (interactive "P")
-  (let* ((root (projectile-acquire-root))
+  (projectile--todos (list (projectile-acquire-root)) arg))
+
+(defun projectile--todos (projects &optional arg)
+  "Collect the TODO-style annotations of PROJECTS into the search reviewer.
+With ARG non-nil, prompt for which keywords to search for.  PROJECTS is a
+list of project roots, so one project and a whole group take the same
+path; see `projectile-search-in-projects' for what changes when there is
+more than one."
+  (let* ((projects (projectile--project-group projects "projects"))
          (keywords (or (if arg
                            (projectile-todos--read-keywords)
                          projectile-todo-keywords)
@@ -11305,15 +11313,16 @@ instead of using all of them."
          (rg-pattern (projectile-todos--rg-pattern keywords))
          ;; the term IS the regexp, so the in-buffer toggles keep working
          (case-fold nil)
-         (candidates (projectile-replace--candidates regexp nil case-fold root)))
+         (candidates (projectile-replace--candidates regexp nil case-fold projects)))
     (projectile-replace--open
      #'projectile-search-mode projectile-search-buffer-name
-     root regexp regexp nil nil case-fold candidates
+     (or (projectile--common-parent projects) "/")
+     regexp regexp nil nil case-fold candidates
      (projectile-prepend-project-name
       (format "No %s annotations found" (string-join keywords "/")))
      ;; The pattern is already word-fenced and ends in a delimiter, so the
      ;; whole-word fence could never match; whole-word mode is not seeded here.
-     nil rg-pattern)))
+     nil rg-pattern projects)))
 
 (defun projectile--buffer-matches-conditions (buffer conditions)
   "Return non-nil if BUFFER satisfies any condition in CONDITIONS.
@@ -14711,6 +14720,25 @@ by its own ignore rules, wherever you happen to be sitting."
      (projectile-prepend-project-name (format "No matches for %s" term))
      projectile-search-whole-word nil projects)))
 
+(defun projectile-project-group-buffers (projects)
+  "Return the live buffers belonging to any of PROJECTS.
+De-duplicated, since two members of a group can nest and a buffer under
+both would otherwise be offered twice."
+  (delete-dups (mapcan #'projectile-project-buffers projects)))
+
+;;;###autoload
+(defun projectile-switch-to-buffer-in-projects (projects &optional prompt)
+  "Switch to a buffer belonging to any of PROJECTS.
+PROMPT overrides the completion prompt.  The current buffer is left out
+of the choices, as `projectile-switch-to-buffer' does."
+  (switch-to-buffer
+   (projectile-completing-read
+    (or prompt "Switch to buffer: ")
+    (delete (buffer-name (current-buffer))
+            (mapcar #'buffer-name (projectile-project-group-buffers projects)))
+    :category 'buffer
+    :caller 'projectile-read-buffer)))
+
 (defun projectile--sibling-group ()
   "Return the projects to treat as a group with the current one.
 
@@ -14746,6 +14774,35 @@ literal string."
              (length siblings) (if (cdr siblings) "s" "")
              (if regexp " regexp" "")))))
 
+;;;###autoload
+(defun projectile-switch-to-buffer-in-sibling-projects ()
+  "Switch to a buffer of the current project or of one related to it.
+Related is what `projectile-switch-sibling-project' means by it."
+  (interactive)
+  (projectile-switch-to-buffer-in-projects
+   (projectile--sibling-group) "Switch to sibling buffer: "))
+
+;;;###autoload
+(defun projectile-multi-occur-in-sibling-projects (&optional nlines)
+  "Do a `multi-occur' in the buffers of the current project and related ones.
+Related is what `projectile-switch-sibling-project' means by it.  With a
+prefix argument, show NLINES of context.
+
+Note this searches the buffers you have open, not the projects on disk -
+`projectile-search-in-sibling-projects' is the one that reads files."
+  (interactive "P")
+  (multi-occur (projectile-project-group-buffers (projectile--sibling-group))
+               (car (occur-read-primary-args))
+               nlines))
+
+;;;###autoload
+(defun projectile-todos-in-sibling-projects ()
+  "Collect TODO-style annotations across the current project and related ones.
+Related is what `projectile-switch-sibling-project' means by it.  See
+`projectile-todos' for what counts as an annotation."
+  (interactive)
+  (projectile--todos (projectile--sibling-group)))
+
 
 ;;; Project bookmarks
 ;;
@@ -16499,6 +16556,9 @@ Magit that don't trigger `find-file-hook'."
     (define-key map (kbd "n p") #'projectile-switch-sibling-project)
     (define-key map (kbd "n f") #'projectile-find-file-in-sibling-projects)
     (define-key map (kbd "n s") #'projectile-search-in-sibling-projects)
+    (define-key map (kbd "n b") #'projectile-switch-to-buffer-in-sibling-projects)
+    (define-key map (kbd "n o") #'projectile-multi-occur-in-sibling-projects)
+    (define-key map (kbd "n t") #'projectile-todos-in-sibling-projects)
     (define-key map (kbd "o") #'projectile-multi-occur)
     (define-key map (kbd "p") #'projectile-switch-project)
     (define-key map (kbd "q") #'projectile-switch-open-project)
@@ -16843,6 +16903,7 @@ search/replace case-sensitive, `--word' makes it match whole words,
       ("J" "toggle related" projectile-toggle-related-file)]
      ["Buffers"
       ("b" "switch buffer" projectile-dispatch-switch-to-buffer)
+      ("nb" "buffer in siblings" projectile-switch-to-buffer-in-sibling-projects)
       ("C-o" "display buffer" projectile-display-buffer)
       ("I" "ibuffer" projectile-ibuffer)
       ("k" "kill buffers" projectile-kill-buffers)
@@ -16859,6 +16920,8 @@ search/replace case-sensitive, `--word' makes it match whole words,
       ("sx" "references" projectile-find-references)
       ("sR" "search (review)" projectile-dispatch-search-review)
       ("ns" "search siblings" projectile-dispatch-search-siblings)
+      ("no" "multi-occur siblings" projectile-multi-occur-in-sibling-projects)
+      ("nt" "todos in siblings" projectile-todos-in-sibling-projects)
       ("st" "todos" projectile-todos)
       ("o" "multi-occur" projectile-multi-occur)
       ("r" "replace" projectile-replace)
@@ -16960,6 +17023,7 @@ search/replace case-sensitive, `--word' makes it match whole words,
          ["Toggle between related files" projectile-toggle-related-file])
         ("Buffers"
          ["Switch to buffer" projectile-switch-to-buffer]
+         ["Switch to buffer in sibling projects" projectile-switch-to-buffer-in-sibling-projects]
          ["Kill project buffers" projectile-kill-buffers]
          ["Save project buffers" projectile-save-project-buffers]
          ["Recent files" projectile-recentf]
@@ -17002,6 +17066,8 @@ search/replace case-sensitive, `--word' makes it match whole words,
          ["Search with ripgrep" projectile-ripgrep]
          ["Search with ag" projectile-ag]
          ["Search in sibling projects" projectile-search-in-sibling-projects]
+         ["TODOs in sibling projects" projectile-todos-in-sibling-projects]
+         ["Multi-occur in sibling projects" projectile-multi-occur-in-sibling-projects]
          ["Project TODOs (review)" projectile-todos]
          ["Replace in project" projectile-replace]
          ["Replace in project (review)" projectile-replace-review]

test/projectile-project-group-test.el

@@ -285,6 +285,66 @@ the two truename'd roots and `parent' to the directory holding them."
                (get-buffer projectile-search-buffer-name))
               :to-equal '("alpha/src/a.txt" "beta/lib/b.txt")))))
 
+
+;;; Buffers across a group
+
+(describe "projectile-project-group-buffers"
+  (it "collects the buffers of every project in the group"
+    (projectile-group-test--with-projects
+      (let ((ba (find-file-noselect (expand-file-name "src/a.txt" alpha)))
+            (bb (find-file-noselect (expand-file-name "lib/b.txt" beta))))
+        (expect (projectile-project-group-buffers (list alpha beta))
+                :to-contain ba)
+        (expect (projectile-project-group-buffers (list alpha beta))
+                :to-contain bb))))
+
+  (it "offers a buffer once when two members of the group nest"
+    (projectile-group-test--with-projects
+      (find-file-noselect (expand-file-name "src/a.txt" alpha))
+      (let ((buffers (projectile-project-group-buffers (list parent alpha))))
+        (expect buffers :to-equal (delete-dups (copy-sequence buffers)))))))
+
+(describe "projectile-switch-to-buffer-in-projects"
+  (it "offers the group's buffers, minus the one you are in"
+    (projectile-group-test--with-projects
+      (let ((ba (find-file-noselect (expand-file-name "src/a.txt" alpha))))
+        (find-file-noselect (expand-file-name "lib/b.txt" beta))
+        (spy-on 'projectile-completing-read :and-return-value (buffer-name ba))
+        (spy-on 'switch-to-buffer)
+        (with-current-buffer ba
+          (projectile-switch-to-buffer-in-projects (list alpha beta)))
+        (let ((offered (cadr (spy-calls-args-for 'projectile-completing-read 0))))
+          (expect offered :to-contain "b.txt")
+          (expect offered :not :to-contain (buffer-name ba)))))))
+
+
+;;; TODOs across a group
+
+(describe "projectile-todos-in-sibling-projects"
+  (it "collects annotations from every project in the group"
+    (projectile-group-test--with-projects
+      (with-temp-file (expand-file-name "src/todo.txt" alpha)
+        (insert "TODO: alpha thing\n"))
+      (with-temp-file (expand-file-name "lib/todo.txt" beta)
+        (insert "FIXME: beta thing\n"))
+      (spy-on 'projectile-sibling-projects :and-return-value (list alpha beta))
+      (cl-letf (((symbol-function 'pop-to-buffer) #'ignore))
+        (projectile-todos-in-sibling-projects))
+      (expect (projectile-test-match-files
+               (get-buffer projectile-search-buffer-name))
+              :to-equal '("alpha/src/todo.txt" "beta/lib/todo.txt"))))
+
+  (it "still works on a single project, unchanged"
+    (projectile-group-test--with-projects
+      (with-temp-file (expand-file-name "src/todo.txt" alpha)
+        (insert "TODO: alpha thing\n"))
+      (spy-on 'projectile-acquire-root :and-return-value alpha)
+      (cl-letf (((symbol-function 'pop-to-buffer) #'ignore))
+        (projectile-todos))
+      (expect (projectile-test-match-files
+               (get-buffer projectile-search-buffer-name))
+              :to-equal '("src/todo.txt")))))
+
 (provide 'projectile-project-group-test)
 
 ;;; projectile-project-group-test.el ends here