git_diff_live 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,106 @@
1
+ / One changed file of the changes page: a <details> whose summary is the file's sticky heading and whose body is the comparison, old on the left and new on the right.
2
+ / locals: file (GitDiffLive::Diff::ChangedFile; file.whole? when it is drawn complete), shown (draw it although it is large), open (true when the reader has just asked for it)
3
+ / The data attributes are what the page holds of this file: changes_controller.js posts them to refresh, which redraws the file only if its digest has moved on, and the same way (whole, shown).
4
+ - shown = local_assigns[:shown]
5
+ - file_params = { path: file.path, **change_range_params, show: (1 if shown) }.compact
6
+
7
+ / A deleted file starts closed: its whole content is red, which is rarely what a review needs to read. However the reader leaves a file, it stays that way through a refresh (changes_controller.js#keepOpenState).
8
+ details.group.rounded.border.border-edge.bg-surface.scroll-mt-2 id=file.dom_id open=(local_assigns[:open] || file.status != :deleted) data-changes-target="file" data-path=file.path data-digest=file.digest data-whole=("true" if file.whole?) data-shown=("true" if shown)
9
+
10
+ summary.sticky.top-0.z-10.flex.items-center.gap-3.px-3.py-2.rounded.bg-surface.cursor-pointer.list-none
11
+
12
+ span.w-3.shrink-0.text-xs.text-fg-muted.transition-transform.group-open:rotate-90 = icon(:fas, :chevron_right)
13
+
14
+ span.shrink-0 = change_status_icon(file)
15
+
16
+ span.font-mono.break-all
17
+ - if file.old_path.present?
18
+ span.text-fg-muted = file.old_path
19
+ span.px-2.text-fg-muted = icon(:fas, :arrow_right)
20
+ = file.path
21
+
22
+ - if file.untracked?
23
+ span.shrink-0.px-1.rounded.border.border-edge.text-xs.text-fg-muted untracked
24
+
25
+ span.shrink-0.font-mono.text-xs = change_counts(file.additions, file.deletions)
26
+
27
+ / The comment on the file, on one line while the file is closed: a deleted file starts that way, and why it went is what the reader wants of it. Open, it is drawn in full under the heading.
28
+ - if file.file_comments.any?
29
+ span.min-w-0.truncate.text-xs.text-fg-muted.group-open:hidden title=change_comment_line(file) = icon(:fas, :comment, change_comment_line(file))
30
+
31
+ span.flex.items-center.gap-4.shrink-0.ml-auto
32
+
33
+ / The whole file only says more than the changes do for a file that has both sides.
34
+ - if file.status.in?([ :modified, :renamed, :copied ]) && file.hunks.any?
35
+ - if file.whole?
36
+ = link_to icon(:fas, :compress, "Changes only"), file_path(**file_params), class: change_link_classes, data: { turbo_stream: true }
37
+ - else
38
+ = link_to icon(:fas, :file, "Whole file"), file_path(**file_params, whole: 1), class: change_link_classes, data: { turbo_stream: true }
39
+
40
+ / Opens the file in the editor at its first change. A deleted file is not there to open.
41
+ - unless file.status == :deleted
42
+ = link_to icon(:fas, :arrow_up_right_from_square, "Open"), change_editor_url(@diff.root.join(file.path), file.first_changed_line), class: change_link_classes, title: "Open in the editor at line #{ file.first_changed_line }"
43
+
44
+ / The comments on the file as a whole (a delete, a move, a binary file), each a bubble with its tail towards the heading.
45
+ - if file.file_comments.any?
46
+ .flex.flex-col.gap-2.px-3.pt-2.pb-3.border-t.border-edge.text-xs.leading-5
47
+ - file.file_comments.each do | comment |
48
+ .relative.self-start.max-w-3xl.px-3.py-2.rounded-lg.bg-raised.text-fg.wrap-anywhere data-comment=comment.side
49
+ span.absolute.-top-1.left-4.size-2.rotate-45.bg-raised
50
+ = change_comment(comment)
51
+
52
+ - if file.binary?
53
+ .px-3.py-2.border-t.border-edge.text-fg-muted Binary file, not shown.
54
+
55
+ - elsif file.status == :unmerged
56
+ .px-3.py-2.border-t.border-edge.text-fg-muted Unmerged: resolve the conflict to see the changes.
57
+
58
+ - elsif file.unchanged_content?
59
+ .px-3.py-2.border-t.border-edge.text-fg-muted = file.old_path.present? ? "Moved, content unchanged." : "No change to the content."
60
+
61
+ - elsif file.large? && !shown
62
+ .px-3.py-2.border-t.border-edge.text-fg-muted
63
+ ' #{ number_with_delimiter file.additions + file.deletions } changed lines.
64
+ = link_to "Show them", file_path(**file_params, show: 1), class: change_link_classes, data: { turbo_stream: true }
65
+
66
+ - else
67
+ / Four columns: old number, old line, new number, new line. Each row's cells share a grid row, so the two sides stay level when a long line wraps.
68
+ / A file with comments has a fifth column for them. The rows come in groups (change_row_groups), each a subgrid on the four code columns, and a group's comments sit beside it in the fifth: a comment taller than its group leaves the space under the group's last row, not between its lines.
69
+ - commented = file.placed_comments.any?
70
+
71
+ .grid.border-t.border-edge.bg-canvas.font-mono.text-xs.leading-5 class="#{ change_grid_classes(file) } [tab-size:4]"
72
+
73
+ - file.hunks.each do | hunk |
74
+
75
+ - unless file.whole?
76
+ .col-span-full.px-3.bg-surface.text-fg-muted.truncate = hunk.heading
77
+
78
+ - change_row_groups(file, hunk).each do | rows, comments |
79
+
80
+ .col-start-1.col-span-4.grid.grid-cols-subgrid.content-start data-rows=true
81
+
82
+ - rows.each do | row |
83
+
84
+ - if row.old
85
+ div class="px-2 text-right select-none #{ change_number_classes(row.old) }" = row.old.number
86
+ div class="px-2 whitespace-pre-wrap wrap-anywhere #{ change_code_classes(row.old) }" = change_code(row.old)
87
+ - else
88
+ .bg-surface
89
+ .bg-surface
90
+
91
+ - if row.new
92
+ div class="px-2 text-right select-none border-l border-edge #{ change_number_classes(row.new) }" = row.new.number
93
+ div class="px-2 whitespace-pre-wrap wrap-anywhere #{ change_code_classes(row.new) }" = change_code(row.new)
94
+ - else
95
+ .bg-surface.border-l.border-edge
96
+ .bg-surface
97
+
98
+ / The comments on this group's first row, each a bubble with its tail towards the code. They follow the reader down a change longer than the window, under the file's heading.
99
+ - if commented
100
+ .col-start-5.px-3.border-l.border-edge.bg-surface.font-sans
101
+ - if comments.any?
102
+ .sticky.top-11.flex.flex-col.gap-2.py-1
103
+ - comments.each do | comment |
104
+ .relative.px-3.py-2.rounded-lg.bg-raised.text-fg.wrap-anywhere data-comment=comment.side
105
+ span.absolute.top-2.-left-1.size-2.rotate-45.bg-raised
106
+ = change_comment(comment)
@@ -0,0 +1,13 @@
1
+ / The changed files by folder. Sticky, so it stays beside the diff while that scrolls. Morphed on every refresh, which keeps its own scroll position.
2
+ nav.hidden.lg:flex.flex-col.gap-3.sticky.top-0.w-80.shrink-0.h-screen.overflow-y-auto.p-3.border-r.border-edge#changes_nav aria-label="Changed files"
3
+
4
+ - @files.group_by { File.dirname(it.path) }.each do | folder, files |
5
+ .flex.flex-col
6
+
7
+ .px-1.pb-1.font-mono.text-xs.text-fg-muted.break-all = folder == "." ? "/" : folder
8
+
9
+ - files.each do | file |
10
+ = link_to "##{ file.dom_id }", class: "flex items-center gap-2 px-1 py-0.5 rounded hover:bg-surface", title: file.path do
11
+ span.w-4.shrink-0.text-center.text-xs = change_status_icon(file)
12
+ span class="truncate grow #{ "line-through text-fg-muted" if file.status == :deleted }" = File.basename(file.path)
13
+ span.shrink-0.font-mono.text-xs = change_counts(file.additions, file.deletions)
@@ -0,0 +1,17 @@
1
+ / What is compared and how much changed, and the fingerprint of the diff these numbers (and the page) were drawn from: changes_controller.js polls for a different one. Replaced on every refresh.
2
+ .flex.flex-wrap.items-center.gap-x-6.gap-y-2#changes_summary data-changes-target="summary" data-fingerprint=@diff.fingerprint
3
+
4
+ .text-fg-muted
5
+ - if @diff.working_tree?
6
+ ' Working tree of
7
+ span.font-mono.text-fg = @diff.branch
8
+ - else
9
+ span.font-mono.text-fg title=@diff.head_sha = @diff.head
10
+ ' against
11
+ span.font-mono.text-fg title=@diff.base_sha = @diff.base
12
+ - unless @diff.base_sha.start_with?(@diff.base)
13
+ | (#{ @diff.base_sha.first(8) })
14
+
15
+ .flex.items-center.gap-2.font-mono
16
+ span = pluralize(@files.size, "file")
17
+ = change_counts(@files.sum(&:additions), @files.sum(&:deletions))
@@ -0,0 +1,2 @@
1
+ / Redraws one file in place, open: its "Whole file" / "Changes only" links and the "Show them" link of a large one.
2
+ = turbo_stream.replace @file.dom_id, partial: "git_diff_live/changes/file", locals: { file: @file, shown: @shown, open: true }
@@ -0,0 +1,42 @@
1
+ / The changes page: the working tree against @diff.base, one section per changed file (_file), with a list of the files down the left.
2
+ / changes_controller.js keeps it up to date: it polls the fingerprint and, when that moves on, posts what the page holds to refresh, which streams back only what is different (refresh.turbo_stream).
3
+ .flex.flex-col.min-h-screen data-controller="changes" data-changes-fingerprint-url-value=fingerprint_path(**change_range_params) data-changes-refresh-url-value=refresh_path(**change_range_params) data-changes-interval-value=(GitDiffLive.configuration.poll_interval.to_f * 1000).round data-action="turbo:before-morph-attribute->changes#keepOpenState"
4
+
5
+ header.flex.flex-wrap.items-center.gap-x-6.gap-y-2.px-4.py-3.border-b.border-edge.bg-surface
6
+
7
+ h1.text-lg.font-semibold = icon(:fas, :code_compare, "Changes")
8
+
9
+ = render "git_diff_live/changes/summary"
10
+
11
+ - if GitDiffLive.configuration.poll_interval.to_f.positive?
12
+ .flex.items-center.gap-2.text-xs.text-fg-muted.transition-opacity title="The page redraws what changes in the working tree" data-changes-target="status"
13
+ span.size-2.rounded-full.bg-emerald-400
14
+ | Live
15
+
16
+ .flex.items-center.gap-2.ml-auto
17
+
18
+ = form_with url: root_path, method: :get, html: { class: "flex items-center gap-2" } do | f |
19
+ / From a commit (base) to the working tree, or to another commit (head): HEAD~1 to HEAD is the last commit on its own.
20
+ = f.label :base, "From", class: "whitespace-nowrap text-fg-muted"
21
+ = f.text_field :base, value: params[:base], placeholder: "HEAD", autocomplete: "off", spellcheck: false, class: change_field_classes
22
+ = f.label :head, "to", class: "whitespace-nowrap text-fg-muted"
23
+ = f.text_field :head, value: params[:head], placeholder: "working tree", autocomplete: "off", spellcheck: false, class: change_field_classes
24
+ = f.button icon(:fas, :arrow_right, "Compare"), type: :submit, name: nil, class: change_button_classes
25
+
26
+ button type="button" class="#{ change_button_classes }" data-action="changes#expand"
27
+ = icon(:fas, :angles_down, "Expand all")
28
+
29
+ button type="button" class="#{ change_button_classes }" data-action="changes#collapse"
30
+ = icon(:fas, :angles_up, "Collapse all")
31
+
32
+ .flex.items-start.grow
33
+
34
+ = render "git_diff_live/changes/nav"
35
+
36
+ main.flex.flex-col.gap-3.grow.min-w-0.p-3
37
+
38
+ = render "git_diff_live/changes/empty"
39
+
40
+ / The files, by path. refresh.turbo_stream replaces, inserts and removes them one at a time.
41
+ .flex.flex-col.gap-3#changed_files
42
+ = render partial: "git_diff_live/changes/file", collection: @files, as: :file
@@ -0,0 +1,29 @@
1
+ / Brings a page up to date with the working tree. @held is what the page holds (path => digest); @files is what is there now.
2
+ / Only the difference is sent: a file whose digest the page already holds is left alone, however many of those there are.
3
+
4
+ / Gone from the changes: committed, reverted or deleted again.
5
+ - @gone.each do | path |
6
+ = turbo_stream.remove GitDiffLive::Diff::ChangedFile.dom_id(path)
7
+
8
+ / Last file first, so a new file always has its neighbour to go in front of: the file after it is either on the page already or was put there a moment ago.
9
+ - following = nil
10
+ - @files.reverse_each do | file |
11
+
12
+ - unless @held[file.path] == file.digest
13
+ - drawn = @whole.include?(file.path) ? @diff.whole(file) : file
14
+ - locals = { file: drawn, shown: @shown.include?(file.path) }
15
+
16
+ - if @held.key?(file.path)
17
+ / Changed. Morphed, so the reader's place in it survives, and it stays open or closed as they left it.
18
+ = turbo_stream.replace file.dom_id, partial: "git_diff_live/changes/file", locals: locals, method: :morph
19
+ - elsif following
20
+ = turbo_stream.before following.dom_id, partial: "git_diff_live/changes/file", locals: locals
21
+ - else
22
+ = turbo_stream.append "changed_files", partial: "git_diff_live/changes/file", locals: locals
23
+
24
+ - following = file
25
+
26
+ / The counts and the list of files are small: sent whole every time. The summary carries the new fingerprint.
27
+ = turbo_stream.replace "changes_summary", partial: "git_diff_live/changes/summary", method: :morph
28
+ = turbo_stream.replace "changes_nav", partial: "git_diff_live/changes/nav", method: :morph
29
+ = turbo_stream.replace "changes_empty", partial: "git_diff_live/changes/empty"
@@ -0,0 +1,17 @@
1
+ doctype html
2
+ / The changes page's own layout: dark, with its own stylesheet (prebuilt, app/assets/builds/git_diff_live.css) and import map (GitDiffLive.importmap). The host supplies only the icon font.
3
+ html lang="en"
4
+ head
5
+ title Changes | #{ GitDiffLive.configuration.root.basename }
6
+ meta charset="utf-8"
7
+ meta name="viewport" content="width=device-width, initial-scale=1.0"
8
+ meta name="turbo-cache-control" content="no-cache"
9
+
10
+ = csrf_meta_tags
11
+ = csp_meta_tag
12
+
13
+ = stylesheet_link_tag(*GitDiffLive.configuration.stylesheets, "git_diff_live", media: :all, data: { turbo_track: :reload })
14
+ = javascript_importmap_tags "application", importmap: GitDiffLive.importmap
15
+
16
+ body.min-h-screen.text-sm.bg-canvas.text-fg.scheme-dark
17
+ = yield
@@ -0,0 +1,6 @@
1
+ # The page's own import map (GitDiffLive.importmap), drawn by the engine. Turbo
2
+ # and Stimulus are the files turbo-rails and stimulus-rails ship.
3
+ pin "application", to: "git_diff_live/application.js"
4
+ pin "@hotwired/turbo-rails", to: "turbo.min.js"
5
+ pin "@hotwired/stimulus", to: "stimulus.min.js"
6
+ pin "controllers/changes_controller", to: "git_diff_live/controllers/changes_controller.js"
data/config/routes.rb ADDED
@@ -0,0 +1,12 @@
1
+ GitDiffLive::Engine.routes.draw do
2
+ # One file redrawn in place: whole, or back to the lines around its changes.
3
+ get "file", to: "changes#file", as: :file
4
+
5
+ # The digest the page polls to learn that the working tree has changed, and
6
+ # the redraw of whatever is no longer what the page holds.
7
+ get "fingerprint", to: "changes#fingerprint", as: :fingerprint
8
+ post "refresh", to: "changes#refresh", as: :refresh
9
+
10
+ # Every changed file, side by side.
11
+ root to: "changes#index"
12
+ end
data/exe/git_diff_live ADDED
@@ -0,0 +1,15 @@
1
+ #!/usr/bin/env ruby
2
+
3
+ # Writes the comments the changes page draws beside each change
4
+ # (GitDiffLive::CLI). Runs in the repository it is called from, whichever
5
+ # folder of it that is.
6
+
7
+ require "open3"
8
+
9
+ require "git_diff_live/cli"
10
+
11
+ root, status = Open3.capture2("git", "rev-parse", "--show-toplevel", err: File::NULL)
12
+
13
+ abort "git_diff_live: not inside a git repository" unless status.success?
14
+
15
+ exit GitDiffLive::CLI.new(root: root.strip).run(ARGV)
@@ -0,0 +1,177 @@
1
+ require "optparse"
2
+
3
+ require_relative "diff"
4
+
5
+ module GitDiffLive
6
+
7
+ # The command line (exe/git_diff_live): how an agent writes the comments the
8
+ # changes page draws beside each change. Plain Ruby, no Rails: it runs in the
9
+ # repository it is called from.
10
+ #
11
+ # git_diff_live changes # the changes that have no comment yet
12
+ # git_diff_live comment <<'EOF' # one comment a line: reference, then the comment
13
+ # app/models/user.rb:+12 Why this line was added.
14
+ # app/models/user.rb:-30 Why that one was removed.
15
+ # app/models/guest.rb:file Why this file was deleted.
16
+ # EOF
17
+ #
18
+ # A reference names a changed line (+12 is line 12 of the file as it is now,
19
+ # -30 is line 30 of the file as it was at the base) or, with "file", the
20
+ # changed file as a whole.
21
+ class CLI
22
+
23
+ USAGE = <<~TEXT
24
+ Usage: git_diff_live changes [--all] [--full] [--base REVISION] [PATH ...]
25
+ git_diff_live comment [--base REVISION] [REFERENCE COMMENT]
26
+
27
+ changes Lists the working tree's changes that have no comment yet, hunk by
28
+ hunk, every changed line with its reference. --all lists the
29
+ commented ones too, with their comments. --full prints long
30
+ changes complete.
31
+ comment Writes comments to #{ Comments::PATH }. Give one as two
32
+ arguments, or any number on standard input, one a line:
33
+
34
+ app/models/user.rb:+12 Why this line was added.
35
+ app/models/user.rb:-30 Why this line was removed.
36
+ app/models/guest.rb:file Why this file was deleted.
37
+
38
+ +12 is line 12 of the file now; -30 is line 30 of the file at the
39
+ base. The page draws the comment beside that line. "file" is the
40
+ file as a whole (a delete, a move, a binary file): the page draws
41
+ the comment under the file's heading.
42
+
43
+ --base The commit the working tree is compared with. Default: HEAD.
44
+ TEXT
45
+
46
+ # A long run of changed lines is cut to this many a side, and a long line
47
+ # to this many characters, unless --full is given.
48
+ SHOWN_LINES = 8
49
+
50
+ SHOWN_WIDTH = 160
51
+
52
+ # "app/models/user.rb:+12 Why this line was added.", or ":file" for the
53
+ # file as a whole. The path may hold spaces.
54
+ LINE = /\A(?<path>.+?):(?:(?<sign>[+-])(?<line>\d+)|file)(?:\s+(?<body>.*))?\z/
55
+
56
+ def initialize(root: Dir.pwd, input: $stdin, output: $stdout, error: $stderr)
57
+ @root = root
58
+ @input = input
59
+ @output = output
60
+ @error = error
61
+ end
62
+
63
+ # Runs one command and returns the exit status.
64
+ def run(arguments)
65
+ arguments = arguments.dup
66
+ options = { base: "HEAD" }
67
+
68
+ OptionParser.new do | parser |
69
+ parser.on("--all") { options[:all] = true }
70
+ parser.on("--full") { options[:full] = true }
71
+ parser.on("--base REVISION") { options[:base] = it }
72
+ end.parse!(arguments)
73
+
74
+ case arguments.shift
75
+ when "changes" then changes(arguments, **options)
76
+ when "comment" then comment(arguments, **options)
77
+ else
78
+ @output.puts USAGE
79
+ 1
80
+ end
81
+ rescue OptionParser::ParseError, Diff::UnknownRevision, Diff::GitError => error
82
+ @error.puts error.message.strip
83
+ 1
84
+ end
85
+
86
+ private
87
+
88
+ # A change is a hunk: the changed lines git drew together, a comment on
89
+ # any of them being its comment. That is the page's unit too, each hunk
90
+ # under its own heading. A file with no hunk (moved, binary) is one change,
91
+ # and so is a file added or deleted once it has a comment on the file.
92
+ def changes(paths, base:, all: false, full: false)
93
+ files = Diff.new(root: @root, base: base).files.reject { it.status == :unmerged }
94
+ files = files.select { | file | paths.any? { file.path == it || file.path.start_with?("#{ it.chomp("/") }/") } } if paths.any?
95
+ left = 0
96
+
97
+ files.each do | file |
98
+ covered = file.whole_change? && file.file_comments.any?
99
+ hunks = file.hunks.map { | hunk | [ hunk, hunk.rows.flat_map { file.comments_beside(it) } ] }
100
+ open = covered ? [] : hunks.select { it.last.empty? }
101
+ bare = file.hunks.empty? && !covered
102
+ left += open.size + (bare ? 1 : 0)
103
+
104
+ next unless all || bare || open.any?
105
+
106
+ @output.puts "#{ file.path } (#{ file.status }#{ " from #{ file.old_path }" if file.old_path })"
107
+ file.file_comments.each { @output.puts " file has: #{ it.body }" }
108
+
109
+ @output.puts " #{ file.binary? ? "Binary" : "Content unchanged" }, no lines to comment on. Comment on the file: #{ file.path }:file" if bare
110
+ @output.puts if file.hunks.empty?
111
+
112
+ (all ? hunks : open).each do | hunk, comments |
113
+ @output.puts " #{ hunk.heading }"
114
+ print_hunk hunk, full
115
+ comments.each { @output.puts " #{ it.reference.delete_prefix("#{ it.path }:") } has: #{ it.body }" }
116
+ @output.puts
117
+ end
118
+ end
119
+
120
+ @output.puts left.zero? ? "Every change has a comment." : "#{ left } #{ left == 1 ? "change" : "changes" } without a comment."
121
+ 0
122
+ end
123
+
124
+ # The hunk's changed lines, removed before added as in a patch, and the
125
+ # unchanged lines between two runs of them (not those around the hunk).
126
+ def print_hunk(hunk, full)
127
+ runs = hunk.rows.chunk_while { | above, below | above.changed? == below.changed? }.to_a
128
+ runs.shift unless runs.first.first.changed?
129
+ runs.pop unless runs.last.first.changed?
130
+
131
+ runs.each do | rows |
132
+ if rows.first.changed?
133
+ print_lines rows.filter_map(&:old), "-", full
134
+ print_lines rows.filter_map(&:new), "+", full
135
+ else
136
+ print_lines rows.map(&:new), nil, true
137
+ end
138
+ end
139
+ end
140
+
141
+ def print_lines(lines, sign, full)
142
+ shown = full ? lines : lines.first(SHOWN_LINES)
143
+
144
+ shown.each do | line |
145
+ text = full || line.text.size <= SHOWN_WIDTH ? line.text : "#{ line.text[0, SHOWN_WIDTH] }..."
146
+
147
+ @output.puts " #{ (sign ? "#{ sign }#{ line.number }" : "").ljust(6) }| #{ text }".rstrip
148
+ end
149
+
150
+ @output.puts " ... | #{ lines.size - shown.size } more, to #{ sign }#{ lines.last.number }" if shown.size < lines.size
151
+ end
152
+
153
+ def comment(arguments, base:, **)
154
+ given = arguments.any? ? [ arguments.join(" ") ] : @input.each_line(chomp: true).reject { it.strip.empty? }
155
+ notes, unread = [], []
156
+
157
+ given.each do | line |
158
+ if (match = LINE.match(line.strip))
159
+ notes << [ match[:path], { "-" => :old, "+" => :new, nil => :file }.fetch(match[:sign]), match[:line]&.to_i, match[:body] ]
160
+ else
161
+ unread << [ line.strip[/\A\S+/], "not a reference: write path:+LINE for an added line, path:-LINE for a removed one, path:file for the file" ]
162
+ end
163
+ end
164
+
165
+ result = Comments.new(root: @root, base: base).write(notes)
166
+ rejected = unread + result.rejected
167
+
168
+ @output.puts "#{ result.written.size } #{ result.written.size == 1 ? "comment" : "comments" } written to #{ Comments::PATH }."
169
+ @output.puts "#{ result.removed } earlier #{ result.removed == 1 ? "comment" : "comments" } removed: the code changed again." if result.removed.positive?
170
+ rejected.each { | reference, reason | @error.puts "Not written: #{ reference }: #{ reason }" }
171
+
172
+ rejected.empty? ? 0 : 1
173
+ end
174
+
175
+ end
176
+
177
+ end
@@ -0,0 +1,181 @@
1
+ require "json"
2
+ require "pathname"
3
+
4
+ module GitDiffLive
5
+
6
+ # Why one change was made: a sentence or two beside a changed line, or under
7
+ # a file's heading. There are two kinds, told apart by +side+.
8
+ #
9
+ # A comment on a line is anchored to the line it was written about, not to a
10
+ # position: +side+ says which version of the file the line is in (:new for an
11
+ # added line, :old for a removed one), +code+ is the line's text, and +line+
12
+ # is the number it had when the comment was written. The page puts the
13
+ # comment beside the changed line with that text, the nearest to +line+ when
14
+ # there are several, so it stays with its code when lines above it come and
15
+ # go, and is left out once that code has been changed again.
16
+ #
17
+ # A comment on a file (+side+ :file, no +line+ or +code+) is about the file
18
+ # as a whole: why it was deleted, moved or added, or what changed in a binary
19
+ # one, which has no lines to point at. It shows for as long as the file is
20
+ # one of the changes.
21
+ Comment = Data.define(:path, :side, :line, :code, :body) do
22
+
23
+ # A line of the store, or nil for one that is not a comment (hand-edited,
24
+ # half-written, a merge marker).
25
+ def self.parse(json)
26
+ fields = JSON.parse(json)
27
+
28
+ return unless fields.is_a?(Hash) && fields.values_at("path", "comment").all?(String)
29
+
30
+ if fields["side"] == "file"
31
+ new(path: fields["path"], side: :file, line: nil, code: nil, body: fields["comment"])
32
+ elsif [ "old", "new" ].include?(fields["side"]) && fields["code"].is_a?(String) && fields["line"].is_a?(Integer)
33
+ new(path: fields["path"], side: fields["side"].to_sym, line: fields["line"], code: fields["code"], body: fields["comment"])
34
+ end
35
+ rescue JSON::ParserError
36
+ nil
37
+ end
38
+
39
+ def file?
40
+ side == :file
41
+ end
42
+
43
+ # A comment on a file is stored without the line and code it does not have.
44
+ def to_json(*)
45
+ JSON.generate({ path: path, side: side, line: line, code: code, comment: body }.compact)
46
+ end
47
+
48
+ # "app/models/user.rb:+12", or "app/models/user.rb:file": how the command
49
+ # line names what the comment is about.
50
+ def reference
51
+ "#{ path }:#{ { old: "-", new: "+", file: "file" }.fetch(side) }#{ line }"
52
+ end
53
+
54
+ end
55
+
56
+ # The comments of a repository: one JSON object per line of
57
+ # .git_diff_live/comments.jsonl, committed with the code they explain.
58
+ #
59
+ # Nothing reads that file to draw the page. A comparison shows the comments
60
+ # the file *gained* between its two ends (Comments.added, off the same git
61
+ # diff that lists the changed files), so a comment written for one commit is
62
+ # shown with that commit, in the working tree before it is committed and in
63
+ # any later comparison that spans it. The file only grows; what is in it from
64
+ # before the comparison is history and is left alone.
65
+ #
66
+ # This class is the writing side, used by the command line (GitDiffLive::CLI):
67
+ #
68
+ # comments = GitDiffLive::Comments.new(root: Dir.pwd)
69
+ # comments.write([
70
+ # [ "app/models/user.rb", :new, 12, "Why this line is here." ],
71
+ # [ "app/models/guest.rb", :file, nil, "Why this file is gone." ]
72
+ # ])
73
+ class Comments
74
+
75
+ DIRECTORY = ".git_diff_live"
76
+
77
+ PATH = "#{ DIRECTORY }/comments.jsonl"
78
+
79
+ # Two branches that each added comments merge without a conflict: git keeps
80
+ # both sets of lines.
81
+ ATTRIBUTES = "comments.jsonl merge=union\n"
82
+
83
+ # What write did: the comments it wrote, the ones it could not place (each
84
+ # with the reason), and how many earlier ones it took out.
85
+ Result = Data.define(:written, :rejected, :removed)
86
+
87
+ # Is +path+ part of the store? The page does not list those files as changes.
88
+ def self.store?(path)
89
+ path.start_with?("#{ DIRECTORY }/")
90
+ end
91
+
92
+ # The comments +file+ (the store, as a Diff::ChangedFile) gained in its
93
+ # comparison. A line that was only moved is on both sides and is not new.
94
+ def self.added(file)
95
+ rows = file.hunks.flat_map(&:rows)
96
+ removed = rows.filter_map { it.old.text if it.old&.kind == :removed }
97
+
98
+ (rows.filter_map { it.new.text if it.new&.kind == :added } - removed).filter_map { Comment.parse(it) }
99
+ end
100
+
101
+ attr_reader :diff
102
+
103
+ def initialize(root:, base: "HEAD")
104
+ @root = Pathname.new(root)
105
+ @diff = Diff.new(root: root, base: base)
106
+ end
107
+
108
+ # Adds comments, each given as [ path, side, line, body ]: a changed line
109
+ # of the working tree, or a changed file (side :file, no line). A comment
110
+ # for a line or file that has one already replaces it. Comments written
111
+ # since the base that no longer explain anything on the page are taken out
112
+ # on the way: a line's when its code has changed again, a file's when the
113
+ # file is no longer one of the changes.
114
+ def write(notes)
115
+ written, rejected = [], []
116
+
117
+ notes.each do | path, side, number, body |
118
+ comment = anchored(Comment.new(path: path, side: side, line: number, code: nil, body: body.to_s.split.join(" ")))
119
+
120
+ if comment.is_a?(String)
121
+ rejected << [ "#{ path }:#{ { old: "-", new: "+", file: "file" }.fetch(side) }#{ number }", comment ]
122
+ else
123
+ written.reject! { it.path == path && it.side == side && it.line == number }
124
+ written << comment
125
+ end
126
+ end
127
+
128
+ placed = @diff.files.flat_map do | file |
129
+ [ [ [ file.path, :file, nil ], file.file_comments ], *file.placed_comments.map { | (side, number), comments | [ [ file.path, side, number ], comments ] } ]
130
+ end.to_h
131
+
132
+ stale = @diff.comments - placed.values.flatten
133
+ replaced = written.flat_map { placed.fetch([ it.path, it.side, it.line ], []) }
134
+ outdated = stale | replaced
135
+
136
+ if written.any? || outdated.any?
137
+ kept = lines.reject { | line | Comment.parse(line).then { it && outdated.include?(it) } }
138
+
139
+ save(kept + written.map(&:to_json))
140
+ end
141
+
142
+ Result.new(written: written, rejected: rejected, removed: stale.size)
143
+ end
144
+
145
+ private
146
+
147
+ # +comment+ ready to store, a line's with the text of the changed line it
148
+ # is to sit beside; or what is wrong with it, as a sentence.
149
+ def anchored(comment)
150
+ file = @diff.file(comment.path)
151
+
152
+ return "#{ comment.path } is not a changed file" if file.nil?
153
+ return "the comment is empty" if comment.body.empty?
154
+ return comment if comment.file?
155
+
156
+ changed = file.changed_lines(comment.side)
157
+ line = changed.find { it.number == comment.line }
158
+
159
+ return comment.with(code: line.text) if line
160
+
161
+ sign = comment.side == :old ? "-" : "+"
162
+ near = changed.map(&:number).min_by(5) { (it - comment.line).abs }.sort.map { "#{ sign }#{ it }" }
163
+
164
+ "#{ sign }#{ comment.line } is not #{ comment.side == :old ? "a removed" : "an added" } line#{ near.any? ? "; the nearest are #{ near.join(", ") }" : "; the file has none (#{ comment.path }:file comments on the file)" }"
165
+ end
166
+
167
+ def lines
168
+ file = @root.join(PATH)
169
+
170
+ file.file? ? file.readlines(chomp: true).reject(&:empty?) : []
171
+ end
172
+
173
+ def save(lines)
174
+ @root.join(DIRECTORY).mkpath
175
+ @root.join(DIRECTORY, ".gitattributes").then { it.write(ATTRIBUTES) unless it.exist? }
176
+ @root.join(PATH).write(lines.map { "#{ it }\n" }.join)
177
+ end
178
+
179
+ end
180
+
181
+ end