lint file path validity

This document was generated from 'src/documentation/print-linter-wiki.ts' on 2025-06-25, 16:32:16 UTC presenting an overview of flowR's linter (v2.2.15, using R v4.5.0). Please do not edit this file/wiki page directly.

File Path Validity ^[overview]

Checks whether file paths used in read and write operations are valid and point to existing files.
This linting rule is implemented in src/linter/rules/file-path-validity.ts.

Configuration

Linting rules can be configured by passing a configuration object to the linter query as shown in the example below. The file-path-validity rule accepts the following configuration options:

• additionalReadFunctions
  The set of functions that should additionally be considered as reading a file path. Entries in this array use the FunctionInfo format from the dependencies query.
• additionalWriteFunctions
  The set of functions that should additionally be considered as writing to a file path. Entries in this array use the FunctionInfo format from the dependencies query.
• includeUnknown
  Whether unknown file paths should be included as linting results.

Examples

my_data <- read.csv("C:/Users/me/Documents/My R Scripts/Reproducible.csv")

The linting query can be used to run this rule on the above example:

[ { "type": "linter",   "rules": [ { "name": "file-path-validity",     "config": {} } ] } ]

Results (prettified and summarized):

Query: linter (1 ms)
   ╰ file-path-validity:
       ╰ definitely:
           ╰ Path C:/Users/me/Documents/My R Scripts/Reproducible.csv at 2.12-74
       ╰ Metadata: {"totalReads":1,"totalUnknown":0,"totalWritesBeforeAlways":0,"totalValid":0,"searchTimeMs":0,"processTimeMs":1}
All queries together required ≈1 ms (1ms accuracy, total 4 ms)

Show Detailed Results as Json

The analysis required 3.9 ms (including parsing and normalization and the query) within the generation environment.

In general, the JSON contains the Ids of the nodes in question as they are present in the normalized AST or the dataflow graph of flowR. Please consult the Interface wiki page for more information on how to get those.

{
  "linter": {
    "results": {
      "file-path-validity": {
        "results": [
          {
            "range": [
              2,
              12,
              2,
              74
            ],
            "filePath": "C:/Users/me/Documents/My R Scripts/Reproducible.csv",
            "certainty": "definitely"
          }
        ],
        ".meta": {
          "totalReads": 1,
          "totalUnknown": 0,
          "totalWritesBeforeAlways": 0,
          "totalValid": 0,
          "searchTimeMs": 0,
          "processTimeMs": 1
        }
      }
    },
    ".meta": {
      "timing": 1
    }
  },
  ".meta": {
    "timing": 1
  }
}

Additional Examples

These examples are synthesized from the test cases in: [lint-file-path-validity.test.ts](https://github.com/flowr-analysis/flowr/tree/main//lint-file-path-validity.test.ts)

Test Case: none

As the script contains no file paths, we expect no issues

Given the following input:

cat("hello")

We expect the linter to report the following:

* no lints

See here for the test-case implementation.

Test Case: simple

Assuming, that file.csv exists, we expect the linter to not report any issues, but to report an invalid file path for file-missing.csv

Given the following input:

cat("hello")
read.csv("file.csv")
read.csv("file-missing.csv")

We expect the linter to report the following:

certainty: LintingCertainty.Definitely, filePath: 'file-missing.csv', range: [3,1,3,28]

See here for the test-case implementation.

Test Case: simple ignore case

If we configure the linter to ignore capitalization, we expect the linter to not report an issue for file.csv, but still report an issue for file-missing.csv

Given the following input:

cat("hello")
read.csv("FiLe.csv")
read.csv("FiLe-missing.csv")

We expect the linter to report the following:

certainty: LintingCertainty.Definitely, filePath: 'FiLe-missing.csv', range: [3,1,3,28]

See here for the test-case implementation.

Test Case: deep

Linting should also work for relative paths, as long as the file exists, we assume path/to/deep-file.csv to exist

Given the following input:

cat("hello")
read.csv("path/to/deep-file.csv")
read.csv("path/to/deep-file-missing.csv")

We expect the linter to report the following:

certainty: LintingCertainty.Definitely, filePath: 'path/to/deep-file-missing.csv', range: [3,1,3,41]

See here for the test-case implementation.

Test Case: deep lax

If we use a relative path that is not valid (we expect there to be no invalid/ folder), we expect the linter to report an issue too

Given the following input:

cat("hello")
read.csv("invalid/path/to/deep-file.csv")
read.csv("invalid/path/to/deep-file-missing.csv")

We expect the linter to report the following:

certainty: LintingCertainty.Definitely, filePath: 'invalid/path/to/deep-file-missing.csv', range: [3,1,3,49]

See here for the test-case implementation.

Test Case: write before

If we use a relative path that is not valid, but we create a file of such a name within the script, we expect the linter to not report an issue

Given the following input:

write.csv("hello", "file-missing.csv")
read.csv("file-missing.csv")

We expect the linter to report the following:

* no lints

See here for the test-case implementation.

Test Case: write before ignore case

If we use a relative path that is not valid, but we create a file of such a name within the script, and ignore case, we expect the linter to not report an issue

Given the following input:

write.csv("hello", "FiLe-missing.csv")
read.csv("file-missing.csv")

We expect the linter to report the following:

* no lints

See here for the test-case implementation.

Test Case: write before never

If the code that is supposed to write the file is never executed, we expect the linter to report an issue for the missing file

Given the following input:

if(FALSE) { write.csv("hello", "file-missing.csv") }
read.csv("file-missing.csv")

We expect the linter to report the following:

certainty: LintingCertainty.Definitely, filePath: 'file-missing.csv', range: [2,1,2,28]

See here for the test-case implementation.

Test Case: const

We should be able to recognize file paths that are bound to variables

Given the following input:

path <- "file.csv"; read.csv(path)

And using the following configuration:

{ includeUnknown: true }

We expect the linter to report the following:

* no lints

See here for the test-case implementation.

Test Case: unknown off

If we configure the linter to do nothing for unknown file paths, we expect it to not report an issue for the unknown file path

Given the following input:

path <- "file" + runif(1) + ".csv"; read.csv(path)

And using the following configuration:

{ includeUnknown: false }

We expect the linter to report the following:

* no lints

See here for the test-case implementation.

Test Case: unknown on

If we configure the linter to report unknown file paths, we expect it to report an issue for the unknown file path

Given the following input:

path <- "file" + runif(1) + ".csv"; read.csv(path)

And using the following configuration:

{ includeUnknown: true }

We expect the linter to report the following:

certainty: LintingCertainty.Maybe, filePath: Unknown, range: [1,37,1,50]

See here for the test-case implementation.