• Code compass :PROPERTIES: :ID: 1683c6ef-701e-476c-a104-56db5582c785 :END:

This package shall guide you in your software development within Emacs. For example, it will point at the code that requires your changes the most and it will suggest you who to ask for help when you are lost.

I have presented some of the capabilities of code-compass in [[https://emacsconf.org/2020/talks/24/][this talk of EmacsConf2020]].

** Credits :PROPERTIES: :ID: 3d3fbd8e-ec09-4dbe-91aa-99713b6fac89 :END:

A significant part of this project relies on [[https://github.com/adamtornhill/code-maat][code-maat]] and the bright mind of his author Adam Tornhill. His books are inspiring and a [[https://pragprog.com/titles/atcrime/your-code-as-a-crime-scene/][suggested]] [[https://pragprog.com/titles/atevol/software-design-x-rays/][read]].

** Features :PROPERTIES: :CREATED: [2022-04-30 Sat 21:53] :ID: 9c50d648-8562-497e-93d4-088db1a326a8 :END:

Use =c/cheatsheet= to have a quick reference of the available commands and their aim. Check the =Release Checklist= heading for more information about them.

** Installation and Dependencies :PROPERTIES: :CREATED: [2020-12-11 Fri 19:10] :ID: 6d691473-a522-46cf-ae41-09fd5c2c69df :END:

Please run =c/doctor= if you encounter errors in running this tool

Note: I label dependencies as optional when the commands needing the dependency warn you they cannot execute because the dependency is missing.

This project depends on the following external dependencies:

• Git
• Python 3
• Java 8 or above
• code-maat
• cloc
• graph-cli (optional - only few commands will not succeed)
• gource (optional)

And the following Emacs packages:

• async.el
• dash.el
• f.el
• s.el
• simple-httpd

If you use =use-package= and you are on a Linux system, this will take care of the Emacs installation:

#+begin_src elisp :noeval (use-package async) (use-package dash) (use-package f) (use-package s) (use-package simple-httpd)

(use-package code-compass :load-path "~/.emacs.d/lisp") #+end_src

For Docker, the Code Maat image, cloc and graph-cli run the following script:

#+begin_src sh :noeval

Docker is only necessary if you want to use that instead of the (automatically downloaded) JAR file

see here for how to install in systems different from Linux Debian: https://gist.github.com/rstacruz/297fc799f094f55d062b982f7dac9e41

#sudo apt install docker.io; #sudo systemctl start docker;

after you manage to run docker successfully

#git clone https://github.com/adamtornhill/code-maat.git; #cd code-maat; #docker build -t code-maat-app .

sudo apt install cloc;

cd /tmp; curl https://bootstrap.pypa.io/get-pip.py -o get-pip.py; # from here https://pip.pypa.io/en/stable/installing/ python get-pip.py --user pip3 install --user graph-cli #+end_src

For trying things out in a clean Emacs:

#+begin_src elisp :noeval :tangle /tmp/code-compass-minimal-setup.el (require 'package) (eval-and-compile (setq package-archives '(("melpa-stable" . "https://stable.melpa.org/packages/") ("melpa" . "https://melpa.org/packages/") ("marmalade" . "https://marmalade-repo.org/packages/") ("org" . "https://orgmode.org/elpa/") ("gnu" . "https://elpa.gnu.org/packages/")))) (package-initialize)

;;; Bootstrap use-package ;; Install use-package if it's not already installed. (unless (package-installed-p 'use-package) (package-refresh-contents) (package-install 'use-package)) (setq use-package-always-ensure 't) (require 'use-package) (require 'diminish) (require 'bind-key) (use-package async) (use-package dash) (use-package f) (use-package s) (use-package simple-httpd) #+end_src

#+begin_src sh :results none emacs -Q -l /tmp/code-compass-minimal-setup.el -l ./code-compass.el #+end_src

** Limitations :PROPERTIES: :CREATED: [2020-12-11 Fri 21:35] :ID: efdeb29f-083a-487c-93d5-48c93fc5b9c8 :END:

The limitations I know:

1. only Git support for now, but I am open to PRs (should be easy because code-maat partially support other VCS already)

2. Adam said that code-maat may fail for code bases larger than 5 million lines. Please report if you observe that is the case, we will find a solution.

3. most likely others I will eventually discover from the issues ;)

** Release Checklist :PROPERTIES: :ID: 8450da84-5aa9-46f9-b65c-5055ae907975 :END:

Releasing this in the wild is exciting, but it will take some time. Here what you can expect.

*** DONE install instructions and dependencies :PROPERTIES: :ID: 27174a0f-186d-4963-a5b3-4704d680476f :END:

• https://ag91.github.io/blog/2020/12/11/emacsconf2020-first-steps-towards-emacs-becoming-your-code-compass/ *** DONE hotspots :PROPERTIES: :CREATED: [2020-12-18 Fri 18:01] :ID: 00f4d809-e7e0-4f29-a2af-30fa07a080e7 :END: :LOGBOOK: CLOCK: [2020-12-18 Fri 18:01]--[2020-12-18 Fri 18:01] => 0:00 :END:
• hotspots analysis: https://ag91.github.io/blog/2020/12/18/emacs-as-your-code-compass-finding-code-hotspots/
• hotspots evolution: https://ag91.github.io/blog/2020/12/24/emacs-as-your-code-compass-looking-at-hotspots-evolution/
• hotspots analysis for microservices: https://ag91.github.io/blog/2021/04/08/emacs-as-your-code-compass-find-hotspots-in-micro-services/ *** DONE software complexity :PROPERTIES: :ID: 6847956b-75c1-4ad7-b911-1994a21a26ac :CREATED: [2020-12-27 Sun 14:10] :END:
• https://ag91.github.io/blog/2020/12/27/emacs-as-your-code-compass-how-complex-is-this-code/

*** DONE code churn :PROPERTIES: :ID: 04b3a73e-60f7-4a6c-87d7-10ff978e24b4 :CREATED: [2021-01-01 Fri 16:54] :END:

• https://ag91.github.io/blog/2021/01/01/emacs-as-your-code-compass-how-much-code-we-produced-for-this-repository-lately/ *** DONE change coupling :PROPERTIES: :ID: 59df8e40-e5d3-47dc-b9da-10666301acc8 :END:
• https://ag91.github.io/blog/2021/01/07/emacs-as-your-code-compass-how-related-are-these-modules/ *** DONE use case of coupling: find coupled files :PROPERTIES: :CREATED: [2021-01-12 Tue 22:16] :ID: 29de5da7-8ba0-46a7-8afa-397b02d4642d :END:
• https://ag91.github.io/blog/2021/01/12/emacs-as-your-code-compass-let-history-show-you-which-files-to-edit-next/ *** DONE code communication :PROPERTIES: :CREATED: [2021-01-22 Fri 20:32] :ID: ceb52892-7b08-4171-8887-670254989b4c :END: :LOGBOOK: CLOCK: [2021-01-12 Tue 22:16] :END:
• [[https://ag91.github.io/blog/2021/01/22/emacs-as-your-code-compass-find-collaborators-you-should-(chit)-chat-with/]] *** DONE code knowledge :PROPERTIES: :CREATED: [2021-01-31 Sun 11:48] :ID: 04064490-aaa7-44c3-a31c-a8d223db31a0 :END: :LOGBOOK: CLOCK: [2021-01-22 Fri 20:32] :END:
• https://ag91.github.io/blog/2021/01/28/emacs-as-your-code-compass-who-can-i-ask-for-help/ *** DONE code stability :PROPERTIES: :ID: fca4bd0a-8c67-4482-8692-a32f98ea2438 :CREATED: [2021-02-06 Sat 16:42] :END:
• https://ag91.github.io/blog/2021/02/06/-emacs-as-your-code-compass-how-stable-is-my-code/ *** DONE fragmentation :PROPERTIES: :ID: b72b368e-7436-4311-a0e6-97b71b8f2260 :CREATED: [2021-02-12 Fri 19:19] :END: :LOGBOOK: CLOCK: [2021-02-06 Sat 16:42] :END: https://ag91.github.io/blog/2021/02/11/emacs-as-your-code-compass-how-fragmented-is-the-knowledge-of-this-file/ *** DONE word analysis :PROPERTIES: :CREATED: [2021-02-20 Sat 19:14] :ID: 46dcf690-2294-47fd-bc33-e1699eba845a :END:
• https://ag91.github.io/blog/2021/02/20/emacs-as-your-code-compass-what-is-this-text-about----without-me-reading-it/ *** DONE use case of coupling: generate todos for current file :PROPERTIES: :CREATED: [2021-03-05 Fri 00:17] :ID: a5e1f2f8-3836-4092-bbc7-2943aa2ff186 :END:
• https://ag91.github.io/blog/2021/03/04/emacs-as-your-code-compass-what-files-do-i-need-to-change-next/ *** DONE integrate gource :PROPERTIES: :CREATED: [2021-03-04 Thu 10:34] :ID: 63b080a9-859b-4863-af5f-2d6eed8bd215 :END: https://ag91.github.io/blog/2021/03/19/emacs-as-your-code-compass-watch-history-with-gource/ *** DONE file-churn icon :PROPERTIES: :CREATED: [2021-02-24 Wed 21:47] :ID: c4809753-ff55-4726-81d7-e1caa37b60cd :END:
• https://ag91.github.io/blog/2021/03/26/emacs-as-your-code-compass-a-gentle-trigger-for-maintenance/ *** DONE main contributors notification :PROPERTIES: :ID: da34e784-028f-4d04-81ec-baa267c9c668 :END:
• https://ag91.github.io/blog/2021/04/18/emacs-as-your-code-compass-quietly-show-who-can-help/ *** TODO functions complexity

** License [[https://www.gnu.org/licenses/gpl-3.0.html][GPLv3]]

*** Dependencies [[https://github.com/d3/d3/][d3]]:

License: [[https://opensource.org/licenses/BSD-3-Clause][BSD-3]]

Copyright 2010-2020 Mike Bostock

** Contributing :PROPERTIES: :CREATED: [2020-12-11 Fri 21:40] :ID: f1b0881f-1c66-49d6-ac46-aecd8dbe9e64 :END:

If you have ideas or wishes, just open an issue and I will look into it! Thanks for caring. ** Alternatives :PROPERTIES: :CREATED: [2020-12-18 Fri 16:00] :ID: 77dac754-8a76-4234-bb1c-0f4e0ea6cb46 :END:

• [[https://codescene.com/][CodeScene]]: this is the code analysis tool of Adam Tornhill which organizations can use to manage their software and organizational complexity. Code-compass learns from CodeScene and adapts to empower you.
• [[https://github.com/textarcana/code-risk/tree/master/bin][code-risk]]: this is a set of scripts Noah Sussman's uses to find quality issues in repositories. Code-compass includes these and make them easily accessible to you.
• [[https://github.com/smontanari/code-forensics][code-forensics]]: this makes available code-maat analyses in a node application. Code-compass offers a subset of these for now and focuses more on supporting you while you edit your project. (Thanks @BlankSpruce to share this repository!)
• [[https://github.com/aspiers/git-deps/][git-deps]]: this shows you dependencies between git commits. Hopefully code-compass will integrate this project to help you when, for example, you are struggling to identify the commit that broke your release.
• ???