Add/export a readable wrapper for testing whether a linter is on an expression or the whole file

[MichaelChirico]

We've got (minor perturbations of) this little idiomatic piece at the top of basically every linter:

lintr/R/cyclocomp_linter.R

Lines 13 to 15 in 23b06bd

	if (!is.null(source_file[["file_lines"]])) {
	# abort if source_file is entire file, not a top level expression.
	return(NULL)

lintr/R/line_length_linter.R

Line 13 in 23b06bd

if (is.null(source_file$file_lines)) return(list())

lintr/R/missing_argument_linter.R

Line 11 in 23b06bd

if (is.null(source_file$full_xml_parsed_content)) return(list())

This is too obscure to a first-time reader. We should add a wrapper of this expression that makes it clear what's being done/why, and also export it for use in custom downstream linters.

[AshesITR]

Good idea. is_complete_file(source_file, require_xml = FALSE)?
I remember the is.null() check on xml_parsed_content being used in some places specifically because it can happen that xmlparsedata fails or returns invalid XML.

Impl would be something like

if (require_xml) {
  !is.null(source_file[["full_xml_parsed_content"]])
} else {
  !is.null(source_file[["file_lines"]])
}

[MichaelChirico]

Twice now I've been bitten by the require_xml part so this helper will do wonders for developers who don't understand the arcana of xml being sometimes present, sometimes not.

OTOH, maybe we could add a "dummy tree" when parsing fails and we can't add a real AST? Something as simple as

<xml>
<exprlist>
  <COMMENT>Parsing this file failed to generate a valid AST</COMMENT>
</exprlist>

Currently the failure mode is highly obscure:

══ Failed tests ══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════
── Error (test-error.R:46:3): returns the correct linting ───────────────────────────
Error in `UseMethod("xml_find_all")`: no applicable method for 'xml_find_all' applied to an object of class "NULL"
Backtrace:
    ▆
 1. └─lintr::expect_lint("\\", rex(expected_message)) at test-error.R:46:2
 2.   └─lintr::lint(file, ...) at lintr/R/expect_lint.R:56:2
 3.     ├─lintr::flatten_lints(linters[[linter]](expr)) at lintr/R/lint.R:113:8
 4.     │ ├─base::structure(flatten_list(x, class = "lint"), class = "lints") at lintr/R/utils.R:22:2
 5.     │ └─lintr::flatten_list(x, class = "lint")
 6.     │   └─lintr assign_item(x) at lintr/R/utils.R:43:2
 7.     │     └─base::inherits(x, class) at lintr/R/utils.R:35:4
 8.     └─linters[[linter]](expr) at lintr/R/lint.R:113:8
 9.       └─xml2::xml_find_all(xml, xpath) at lintr/R/if_else_match_braces_linter.R:36:4

[AshesITR]

Better use xml_missing() than a fake AST -- especially one that could be the result of valid code.