Jump to a file/Jump to a directory

[masatake]

I'm reading a software written in Ruby on Rails. I'm not familiar with the framework and Ruby.

Just reading source files is insufficient and inefficient in understanding the target software.
The definitions of modules and classes are widely spread throughout the source tree. Reading source files wastes time unless you know the framework's conventions. Ruby on Rails is so popular.
Getting such knowledge may not be hard. But if I have to understand the target software based on a private and/or minor framework, what will happen?

I need to understand the source tree. I have thought about improving ctags/readtags and citre in this direction.

In ctags, I'm trying to add FileSystem (pseudo) parser. The parser has "file" and "dir" kinds. The parser extracts the names of files even if ctags has no suitable parser for the files.
With initForeignTagEntry function, a prototype Tree parser emits the file and dir tags.

[yamato@dev64]~/var/ctags-github% ./ctags --list-kinds-full=FileSystem
#LETTER NAME     ENABLED REFONLY NROLES MASTER DESCRIPTION
D       dir      yes     no      0      NONE   directories
S       symlink  yes     no      0      NONE   symbolic links
X       excluded no      no      0      NONE   filesystem objects excluded by the ctags command line
Y       unknown  yes     no      0      NONE   unknown filesystem objects
f       regular  yes     no      0      NONE   regular files
[yamato@dev64]~/var/ctags-github% tree t                              
t
├── a
│   └── foo.c
└── b
    └── bar.c

3 directories, 2 files
[yamato@dev64]~/var/ctags-github% tree t | ./ctags --sort=no --fields=+zZkK --options=optlib/tree.ctags --_interactive=oneshot:t.tree -o - 
t	t.tree	/^t$/;"	kind:dir
foo.c	t.tree	/^│   └── foo.c$/;"	kind:unknown	scope:dir:t/a
a	t.tree	/^├── a$/;"	kind:dir	scope:dir:t
bar.c	t.tree	/^    └── bar.c$/;"	kind:unknown	scope:dir:t/b
b	t.tree	/^└── b$/;"	kind:dir	scope:dir:t
[yamato@dev64]~/var/ctags-github% tree t | ./ctags --sort=no --fields=+zZkK --options=optlib/tree.ctags --_interactive=oneshot:t.tree -o - | ./readtags -et - -l  -F '(list (if $scope-name (list $scope-name "/" $name) $name) #t)' | tree --fromfile .
.
└── t
    ├── a
    │   └── foo.c
    └── b
        └── bar.c

4 directories, 2 files

Ctags may be able to reproduce the source tree structure.
I hope to do something interesting with this feature.

I'm also exploring my idea on Citre's side.

#include "header"

When you press M-. on "header", citre brings you to a buffer which opens the header.
Do I want this behavior if I'm unfamiliar with the target software?

It would be nice if Citre could bring me to a buffer visualization where the header is in the source tree. To evaluate my idea, I wrote xref-dir-location. If a tag's language is FileSystem or the kind of tag is file, Citre makes a xref with xref-dir-location instead of xref-file-location.

Screencast.From.2025-04-19.03-36-23.mp4

The default handler of the current implementation utilizes dried.
From the dried buffer, it is hard to feel the structure of the source tree, though it is better than finding the file.

However, the function for making the marker is customizable.
These days, tree-oriented elisp libraries are available:

https://github.com/emacsorphanage/direx
https://github.com/tilmanrassy/emacs-dir-treeview
https://github.com/Alexander-Miller/treemacs
https://codeberg.org/fourier/ztree

Jumping to an entry in the source tree looks like an interesting feature.

[masatake]

I forgot to add "speedbar" to the list of the elisp libraries.

[AmaiKinono]

It looks doable, but maybe we should ask in the first place: what's a good way to explore an unfamiliar codebase?

It would be nice if Citre could bring me to a buffer visualization where the header is in the source tree.

This will help, but to me the "visualization" does not necessarily mean a directory tree. I don't even think this is useful for most C/C++ project given their conventional flat directory structure (maybe I am wrong).

Instead, a visualization of logical relationships between entities, like A references B, A implements/inherits B, may be more useful. These kinds of relationships naturally form a graph, which is easier to visualize in a GUI than in Emacs. Some examples:

• Various kinds of graphs in the code reading tool "understand"
• org-roam-server, visualizing links between notes(files):

Based on the goodies that ctags already offers (the so called dependency reference tags, which I believe is usable for many languages by now), we can focus on relationships between modules (or headers, files). A tool like org-roam-server will fit this, but that would require a dedicated GUI tool, or a Emacs plugin that serves such a GUI in a web browser, which to me is acceptable, but not very aesthetic to people who want to live in Emacs.

However, visualizing a graph in a text-based tool may be a serious challenge, and I haven't seen any example of this. Some of my ideas:

• Reusing the UI of citre-peek and browse a single chain in a graph is possible.
• Based on the concept of centrality, we can assign a score of importance to every node in a module dependency graph, then we can sort it and show it in a buffer, one node per line. So the user could know which are the most important modules and read them first. Commands to visit dependencies of a node and nodes that depend a node may be useful in such a UI.

[masatake]

Thank you for the great input.

I have implemented a small tool that I want to use today.
The tool shows where a name is located in a source tree.

Screencast.From.2025-04-21.02-44-10.mp4

(defun find-common-prefix0 (candidate strlist)
  (if (cl-every
       (lambda (str) (string-prefix-p candidate str))
       strlist)
      candidate
    (find-common-prefix0 (directory-file-name (file-name-directory candidate))
			 strlist)))

;;(find-common-prefix (list "/a/c/d/e" "/a/c" "/a/c/d/x"))
;; => /a/c
(defun find-common-prefix (strlist)
  (when (cdr strlist)
    (let* ((elt (car strlist))
	   (dir-name (directory-file-name (file-name-directory elt))))
      (find-common-prefix0 dir-name strlist))))

(defvar xref-show-fs-tree-seed nil)
(defun xref-fs-tree-show0 (files obuf level)
  (with-current-buffer obuf (erase-buffer))
  (let ((level-args (if level (list "-L" (number-to-string level)) (list))))
    (when files
      (with-temp-buffer
	(mapc #'(lambda (f) (insert f) (newline)) files)
	(apply #'call-process-region nil nil "tree" nil obuf t "--fromfile" "."
	       level-args))
      (with-current-buffer obuf (goto-char (point-min))
			   (setq-local xref-show-fs-tree-seed files))
      (display-buffer obuf))))

(defun xref-fs-tree-set-level (level)
  (interactive "nLevel: ")
  (xref-fs-tree-show0 xref-show-fs-tree-seed
		      (current-buffer)
		      level))

(defvar xref-fs-tree-mode-map
  (define-keymap :suppress t
    "q" 'kill-buffer
    "1" #'(lambda () (interactive) (xref-fs-tree-set-level 1))
    "2" #'(lambda () (interactive) (xref-fs-tree-set-level 2))
    "3" #'(lambda () (interactive) (xref-fs-tree-set-level 3))
    "4" #'(lambda () (interactive) (xref-fs-tree-set-level 4))
    "5" #'(lambda () (interactive) (xref-fs-tree-set-level 5))
    "6" #'(lambda () (interactive) (xref-fs-tree-set-level 6))
    "7" #'(lambda () (interactive) (xref-fs-tree-set-level 7))
    "8" #'(lambda () (interactive) (xref-fs-tree-set-level 8))
    "9" #'(lambda () (interactive) (xref-fs-tree-set-level 9))))

(defun xref-fs-tree-show ()
  (interactive)
  (let ((files (list))
	(obuf (get-buffer-create "*xref-fs-tree*")))
    (save-excursion
      (goto-char (point-min))
      (while-let ((xref (xref-next-line-no-show))
		  (loc (xref-item-location xref)))
	(when (xref-file-location-p loc)
	  (setq files (cons (xref-file-location-file loc)
			    files)))))
    (let* ((prefix (find-common-prefix files))
	   (prefix-len (if prefix (length prefix) 0))
	   (files (mapcar (lambda (f) (substring f prefix-len)) files)))
      (with-current-buffer obuf
	(kill-all-local-variables)
	(setq major-mode 'xref-fs-tree-mode
	      mode-name "XREF-FS-TREE")
	(use-local-map xref-fs-tree-mode-map)
	(buffer-disable-undo))
      (xref-fs-tree-show0 files obuf nil))))

(define-key xref--xref-buffer-mode-map "T" 'xref-fs-tree-show)

I used the word level, but it should be depth.