panglesd/diffcessible

diffcessible's Issues

Display current operation in status bar

Currently, we have a region at the top which displays the current operation.

However, this region is using the "diff" format. For instance, Creation of files are displayed like this:

--- a/dev/null
+++ b/path/to/new/file

It would be better to have a single, more explicit, line:

Creation of `path/to/new/file`

and similarly for other operations: rename, deletion, ...

This requires to replace the string_of_operation function in interactive_viewer.ml into a function that takes a value of type Patch.operation and creates the relevant string from the value.

Create a help panel

Add a panel that contains the list of keybindings with an explanation on what they do.

The panel would occupy on the whole screen, and its visibility would be toggled using a key (such as h).

Implement Word Diff Algorithm

Create a README

Create a README

Compute and display number of added and removed lines in status bar

The top bar currently displays the current operation shown.

It would be nice to also show the number of added and removed lines. This would have to be computed from the list of hunks.

Use keyboard arrows for scrolling

Currently, it's only possible to scroll the visible part of the hunk via the mouse. This isn't a very accessible interface.

The goal of this task is to add the following key-bindings:

• up: Scrolls toward the top.
• down: Scrolls toward the bottom.

Scrolling is implemented by Nottui_widgets. We are currently using W.scrollbox but we'd need to switch to W.vscroll_area to have the keybindings above.

W.scrollbox is a nottui widget that implements scrolling using the mouse. The "scrolling state" is hidden in the widget and we cannot add any shortcut to modify it. So, we cannot use this widget for our purpose.
W.vscroll_area is a widget that implements (vertical) scrolling using the keyboard.

So, solving this task requires to switch to W.vscroll_area. This function takes as input a scroll_state and a function to modify the scroll state, that need to be create. It will be handy to be able to modify the scroll state from the outside of the function to add new keybindings.

example.diff do not show a file with several hunks

The example.diff file, which is useful to quickly try out the project, do not contain a file that would show more than one hunk.
This is needed to test #33

@iAlexeze Are you interested in fixing this issue, in a different PR?

Bind `j` and `k` to scrolling

Requires #14 to be done first.

Keyboard arrows are common to scroll, but so are j and k on TUIs. The goal of this task is to add the following bindings:

• j to scroll down,
• k to scroll up.

Keybindings can be either added in interactive_viewer.ml alongside the other key bindings, or in the keybindings defined in the vscroll_area function, in nottui_widgets.ml

Show line numbers in diffs

Showing line numbers in a diff file is tricky as each line can have a different number before and after the patch is applied.

See for example, this diff from the example.diff file:

diff --git a/bin/main.ml b/bin/main.ml
index e03c4a4..cb71f31 100644
--- a/bin/main.ml
+++ b/bin/main.ml
@@ -1,7 +1,9 @@
 open Diffcessible
 
 let main () =
-  Interactive_viewer.start ()
+  let s = In_channel.input_all In_channel.stdin in
+  let patch = Patch.to_diffs s in
+  Interactive_viewer.start patch
 
 open Cmdliner
 

The line numbers are start at 1 in both files, as indicated by the @@ line, but then diverges due to there being more added lines than removed lines.
The line numbers are as follow:

1  1  open Diffcessible
2  2  
3  3  let main () =
4    -  Interactive_viewer.start ()
   4 +  let s = In_channel.input_all In_channel.stdin in
   5 +  let patch = Patch.to_diffs s in
   6 +  Interactive_viewer.start patch
5  7  
6  8  open Cmdliner
7  9  

Add CI testing using Github Actions

The OCaml community has the awesome ocaml-ci but for some reason we cannot enable it on this project until next week.

In the meantime, it would be useful to have a CI that does the following:

• Setup an OCaml environment with setup-ocaml
• Checkout the project source code.
• Install the project dependencies with opam install --deps-only -t -y .
• Run the tests with dune runtest.
• Check formatting with dune build @fmt.

This is a medium issue.

Show line numbers in side-by-side diffs

Side-by-side diffs are added in #32

As new columns are added, it is natural to have extra columns for line numbers. Line numbers should be toggleable with a keybinding.

A more representative example file

The file diff.example is nice for easily and quickly trying out the program but is not enough for testing it.

We need a new diff file that contains:

• All the different operations (for example, to test #27)
• A hunk with only deleted lines
• A hunk with only added lines
• A hunk with both.

Ideally, this file would be generated by first crafting two directories with slightly different files in them and running on them git diff --no-index.

Add colors to output

Even if they are not visible by everyone, colors help to read a diff.

It would be nice to add green and red background colors to the added and removed lines, in the output.

Add dependencies to the `dune-project` file.

Outreachy Summer 2024: An accessible diff viewer

Outreachy Summer 2024: An accessible diff viewer

This issue is point of introduction to the project for Outreachy applicants.

First of all: welcome! We are happy to have you interested in the project.

In this issue, we gather many information that is relevant before contributing: more explanation on the project, but also resources worth reading, some instructions to set up the project, and a list of issues with some hint on the difficulty.

So, make sure to read this issue till the end! And do not hesitate to reply on it to ask any question that is related to the project! (For questions that are non-specific to the project, such as issues in setting up OCaml, please prefer other channel, such as the OCaml discord server).

The project

Looking at the difference between two files is one of the most common activity in open source work.
It happens when reviewing a pull request, inspecting a commit and in many other situation.

The differences are usually displayed following a specific format, added lines being prefixed with a +, removed ones by a - and common one without prefix. Such format is called a "diff". Here is a simple one:

  common words
- removed line
+ added line

However, in complex situation, reading such diff is not always easy. Many tools have been to made to improve the situation and make the diff reviewing easier: as shown above, the use of colours to distinguish between added and removed lines (traditionally green and red), use of a bold face to get the attention on the modified part of the line at the word level, the display of the two files side-by-side, ...

However, most of the improvements mentioned above:

• Are made for "generic" diffing of files. Some files may have very long lines and be unsuitable for the current diff output.
• Are restricted to sighted people.

The goal of this project is to develop a visualization tool on top of Git diff. The visualization tool is a terminal UI, and the main task of the internship is to make it highly accessible to screen readers.

The current state of the project

This repository contains a minimal TUI to visualize diffs, as a starting point for the internship.

It uses several libraries:

• The patch library to parse and print diffs,
• The notty library to "declare" terminal layout,
• The lwd library to make the UI reactive,
• The nottui library to bind lwd and notty,
• The cmdliner library to generate a command line.

It is built using the dune build system.

The project is still quite small. The bin/ directory contains the code for the command line, relying mostly on the cmdliner library.
The lib/ directory contains the code for the UI, using lwd and nottui.
The vendor/ directory contains the vendored libraries: dependencies that needed to be slightly modified, and as such were included in the source. Unless for specific reasons, you won't need to modify the code in this directory. It can be useful to read though.
The rest of the files are configuration or documentation files (dune files, README.md, LICENSE, ...).

How to understand the code

Although the number of lines of code in this project is fairly small, it is very dense and can be quite hard to understand at first. But with time, work and experience it will become clear! So don't despair if at first, it seems obscure.

The first requirements to understand the code is to have the basics of OCaml: its syntax, but also the functional and declarative idioms it uses. The ocaml.org website provides some tutorials and guides, and there is also the book Real World OCaml which is available online.

Then, it is important to have a good idea on how the libraries used in this project work. Cmdliner has some documentation, that should be understood for any task that requires modifying the command line.

The Text User Interface is made using a concept called "Functional Reactive Programming". There is some explanation on that in the Lwd homepage. Basically, the UI layout is built from basic mutable variables, created with Lwd.var. Similarly to the React framework, any change in the value of a basic variable will trigger a recomputation of the UI, which will be updated where needed.

Setting up the project

First, you need to have OCaml up and running on your local machine. See the tutorial Installing OCaml.

Then, you need to clone this repository. Once you have that, go to the directory and install the dependencies with the following command:

$ opam install . --deps-only --with-test

Once the dependencies have been installed, try to build the project.

$ dune build

If dune is still complaining about missing dependencies, maybe your environment is not in sync with opam. In this case, on Linux and Mac eval $(opam env) should fix it.

You can now run the binary created by the project:

$ dune exec diffcessible diff.example
$ # Or to see the man page of the tool:
$ dune exec -- diffcessible  --help

Claiming an issue

Once you get a reasonable understanding of the code and have the project set up, you can consider contribute to the project. In order to do so, you have at the end of this section a list of good first issues.
As to avoid duplicated work, when you decide to work on an issue, you need to be assigned on it: this way, you can work on it without the pressure to finish before someone else opens a PR fixing the issue! However, in order to be assigned an issue, you need to be able to build the project first.
To be assigned an issue, comment on the issue thread with a screenshot of your computer with the --help page, and ask to be assigned to the issue! When you are assigned an issue, we can provide more guidance on it if needed.

Good first issues:

• #3
• #4
• #5
• #11
• #12
• #14
• #17
• #18
• #19
• #5
• #44
• #46

Medium issues:

• #8
• #9
• #15
• #45

Asking for help

Please do ask for help if you are blocked on something!

There are two different kind of help that you might require: general help with OCaml, the tooling ; and help specific to this project.

To get general help on OCaml, the discord server might be the best option. It contains a "#outreachy" channel as well as a #beginner channel. The OCaml discuss is also a place where you can get help, it looks more like a forum compared to discord.

Contributing and AI

We want to stress that during the contribution period, AIs should be used with a lot of care. While they are a great tool both to learn and work, they can be very inadequate without mentor or critical sense, moreover they don't know OCaml very well. As mentors, we don't want to review code copy-pasted from an AI.

Conclusion

We are glad to have you here!

More efficient datastructure for storing hunks

Hunks are currently stored in a list and accessed using an index. This operation have to iterate the list from the beginning to reach the desired hunk. Which is slow when looking at the end of a very large diff.

More efficient datastructures for this are: Array or Zipper.

Compute and display number of hunks in the status bar.

It would be nice to display the number of hunks for the current operation, in the top status bar.

For instance:

--- a/path/to/file
+++ b/path/to/file

could become:

--- a/path/to/file
+++ b/path/to/file
7 hunks

Open Outreachy issue

See the example on previous repos

Status bar

It would be useful to have a status bar showing contextual information, for example:

• Name of the file being viewed.
• Index of the current hunk.
• Total number of hunks.

Horizontal scrolling

Vertical scrolling was added in #36, but long lines overflows and the content at the end is not visible.

This intermediate issue is about adding the ability to scroll horizontally.

When assigned this issue, do not hesitate to ask for more information, or help if you are blocked!

Horizontal scrolling

Lines in the diff can be longer than the screen and we need a way to scroll in the horizontal direction.
There is currently a vertical scroll box but not an horizontal one.

The UI is implemented using the Nottui library in interactive_viewer.ml.
Unfortunately, horizontal scrolling is not provided by the library and must be built from more primitive functions. As a reference, vertical scroll is implemented here: https://github.com/let-def/lwd/blob/master/lib/nottui/nottui_widgets.ml#L153

Allow to read the patch from a file

Currently, the executable read a file from a hardcoded path: "diff.example".

We need to be able to pass the file on the command line. This would be a required argument to the command line.

Outreachy Application: How to provide a timeline for the project

Hi @Julow @panglesd,

I am currently writing my application for this project via the Outreachy portal, and one of the prompts asks us to work with you to provide a timeline of the work we plan to accomplish on the project and what tasks we will finish at each step. May I inquire how to best answer this question and which projects you feel are great to include for this?

Thank you very much.

Best regards,
yokurang

Improve the `n` and `p` shortcuts

The n and p shortcuts currently increment and decrement an integer. This integer is used as the index of the hunk to show on the screen.

This is a bad user experience as the integer can be incremented above the number of hunks, which has no visible effect except that the next n will also have no visible effect.

The p shortcuts should not set a value equal or above the number of hunks.
The n shortcuts should not set a negative value.

Navigation between hunks

Pressing n (next) and p (previous) navigates between operations: creation of a file, removal of file, edition, renaming, ...
Each operation contains several hunks of changes, that are displayed one after the other.

It would be nice to be able to only see one hunk, and navigate through them using f (forward) and b (backward).

The top status bar should ideally display the number of the visible hunk, as well as the total number of hunks.

Add keybinding to scroll to the top

#36 has added the ability to scroll.

It would be nice to have a keybinding to scroll back to the top of the displayed operation.

Feel free to ask for help or clarification when working on this issue!

Add a side-by-side display of the diff

Reading diff side-by-side can be very useful:

It would be nice to be able to switch from "normal" to "side-by-side" view by the press of a key.

Implement TUI Landing Page

Colorize addition and removal summary

This issue is a good first issue, and is reserved for first-time contributors!

#30 added a summary of the number of lines added and removed. It would be nice to display these numbers in red and green to improve readability.

If a hunk contains line numbers of different number of digits (and of more than three digits).

Test for the interface

A new entry point in the Interactive_viewer library should be added, which allows to:

• Run the UI in a dummy terminal not connected to a real terminal of a fixed size.
• Send a sequence of predefined events.
• Print the last frame.

This can then be wrapped in a binary and called from a cram test.