clang_tools.patcher

A module to contain the abstractions about creating suggestions from a diff generated by the clang tool’s output.

cpp_linter.clang_tools.patcher.HUNK_HEADER = re.compile('^@@ -(\\d+)(?:,(\\d+))? \\+(\\d+)(?:,(\\d+))? @@')

Matches a unified diff hunk header, e.g. @@ -3,2 +3 @@.

class cpp_linter.clang_tools.patcher.DiffLine(origin: str, content: str, old_lineno: int)[source]

A single line of a DiffHunk.

origin : str

"+" for an added line or "-" for a removed line.

content : str

The line’s text, including its line ending (if any).

old_lineno : int

The line number in the original file (-1 for added lines).

class cpp_linter.clang_tools.patcher.DiffHunk(old_start: int, old_lines: int, new_start: int, new_lines: int, lines: list[DiffLine] = <factory>)[source]

A hunk of a unified diff generated without context lines.

class cpp_linter.clang_tools.patcher.Patch(text: str, hunks: list[DiffHunk])[source]

A unified diff of a file’s original content and a clang tool’s fixes.

text : str

The diff as text (shown in the PR review summary).

hunks : list[DiffHunk]

The parsed hunks of the diff.

classmethod create_from(old: Path, new: bytes, file_name: str) → Patch[source]

Diff the old file against the new content with git diff.

This uses the same diff algorithm (and indent heuristic) as libgit2, so hunks are the same as the ones pygit2 produced before it was dropped.

classmethod parse(diff: str, file_name: str) → Patch[source]

Parse the output of git diff --unified=0 for a single file.

class cpp_linter.clang_tools.patcher.Suggestion(file_name: str)[source]

A data structure to contain information about a single suggestion.

Parameters:
file_name: str

The path to the file that this suggestion pertains. This should use posix path separators.

line_start : int

The file’s line number starting the suggested change.

line_end : int

The file’s line number ending the suggested change.

file_name : str

The file’s path about the suggested change.

comment : str

The markdown comment about the suggestion.

serialize_to_github_payload() → dict[str, Any][source]

Serialize this object into a JSON compatible with Github’s REST API.

class cpp_linter.clang_tools.patcher.ReviewComments[source]

A data structure to contain PR review comments from a specific clang tool.

suggestions : list[Suggestion]

The list of actual comments

tool_total : dict[str, int | None]

The total number of concerns about a specific clang tool.

This may not equate to the length of suggestions because 1. There is no guarantee that all suggestions will fit within the PR’s diff. 2. Suggestions are a combined result of advice from both tools.

A None value means a review was not requested from the corresponding tool.

full_patch : dict[str, str]

The full patch of all the suggestions (including those that will not fit within the diff)

merge_similar_suggestion(suggestion: Suggestion) → bool[source]

Merge a given suggestion into a similar Suggestion

Returns:

True if the suggestion was merged, otherwise False.

serialize_to_github_payload(tidy_version: str | None, format_version: str | None, reused: int = 0) → tuple[str, list[dict[str, Any]]][source]

Serialize this object into a summary and list of comments compatible with Github’s REST API.

Parameters:
tidy_version: str | None

The version numbers of the clang-tidy used.

format_version: str | None

The version numbers of the clang-format used.

reused: int = 0

The number of review comments that were already posted (in a previous review) and thus culled from the new review. This is only used to add a note to the summary.

Returns:

The returned tuple contains a brief summary (at index 0) that contains markdown text describing the summary of the review comments.

The list of suggestions (at index 1) is the serialized JSON object.

class cpp_linter.clang_tools.patcher.PatchMixin[source]

An abstract mixin that unified parsing of the suggestions into PR review comments.

patched : bytes | None

A unified diff of the applied fixes from the clang tool’s output

get_suggestion_help(start, end) → str[source]

Create helpful text about what the suggestion aims to fix.

The parameters start and end are the line numbers (relative to file’s original content) encapsulating the suggestion.

get_tool_name() → str[source]

A function that must be implemented by derivatives to get the clang tool’s name that generated the patched data.

get_suggestions_from_patch(file_obj: FileObj, summary_only: bool, review_comments: ReviewComments, repo_root: str)[source]

Create a list of suggestions from the tool’s patched output.

Results are stored in the review_comments parameter (passed by reference). The file’s name is relative to repo_root.