4.2 Source Groups🔗ℹ

A source group is a specification of what source code Resyntax should analyze, along with which lines within those sources Resyntax is allowed to suggest changes to. Source groups come in four kinds, each corresponding to one of the target flags accepted by the command-line interface:

• Single-source groups, constructed with single-source-group, containing one file restricted to a given set of lines. The --file flag constructs these, with all lines allowed. Note that the CLI doesn’t include a way to specify which lines should be modified at this time, despite the fact that the single-source-group constructor accepts that information. The only difference between a single-source group and a file-source? value is that the source group may contain information about which lines to analyze.

• Directory groups, constructed with directory-source-group, containing every source file within a directory, including files in subdirectories. The --directory flag constructs these.

• Package groups, constructed with package-source-group, containing every file of a locally installed Racket package. The --package flag constructs these. This does not refer to remote packages on the package catalog; Resyntax cannot analyze a package unless it’s currently installed.

• Git repository groups, constructed with git-repository-source-group, containing the files of a local Git repository that have changed relative to some base reference. The --local-git-repository flag constructs these. As with package groups, Resyntax can only analyze Git repositories that have already been cloned onto the current machine. Git repository groups are the only source groups that take advantage of Resyntax’s ability to restrict which lines are analyzed — only the lines actually touched in the diff against the specified base reference, plus a small margin of surrounding context lines (see git-repository-source-group), will be included.

Additionally, any number of source groups can be combined into a single group with source-group-union. This is how the command-line interface handles multiple target flags: each flag becomes a source group, and all of them are unioned into one group describing the entire analysis.

A source group is only a description: it must be resolved with source-group-resolve to produce the actual source code values that Resyntax analyzes. Resolution is when the filesystem, the local package system, or the local Git repository is actually consulted. Resolution does not consult external networked sources; only local information is considered. After resolution, Resyntax "locks in" the set of sources it’s editing. If, after this point, new files are added to a directory group (or a similar addition is made to the files described by a different kind of source group) they will be ignored by Resyntax. However, edits to the contents of files that were included in the source set, but which Resyntax has not started to analyze, will be perceived by Resyntax. This is because source group resolution does not read the contents of each source file into memory yet. That occurs at a later step, on a per-file basis, as Resyntax is analyzing each file.

Unioning is commutative, associative, and idempotent, and empty-source-group is its identity element: source groups form a commutative monoid under union (in fact, a bounded join-semilattice, thanks to idempotence). These laws hold up to equal?:

• (source-group-union g1 g2) is always equal? to (source-group-union g2 g1).

• (source-group-union (source-group-union g1 g2) g3) is always equal? to (source-group-union g1 (source-group-union g2 g3)).

• (source-group-union g g) and (source-group-union g empty-source-group) are both always equal? to g.

This operation is a convenience wrapper around source-group-union-all.

Only the modified lines of each changed file are eligible for suggestions, expanded to include the three lines before and after each modified region. The three-line margin matches what GitHub allows in pull request reviews: comments may only be placed on modified lines and the three lines of context surrounding them, so suggestions within the margin can still be posted as review comments. More generally, a three-line margin is the default amount of extra context that many Unix tools choose when interoperating via the unified diff format, particularly the diff tool.

Resolution discards all files that don’t have the .rkt extension. This is where the command-line interface’s restriction to .rkt files is implemented.